teksilo_core/

text_surface.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! `TextSurface` — "the widget the caret is in", as an application sees it.
//!
//! # Why the framework has to answer this
//!
//! An application that wants **one** Undo command — one chord, one menu row,
//! routed to whatever the writer is actually editing — handles the
//! [`edit.undo`](crate::shortcut::StandardEdit::Undo) intent. From the chord,
//! the walk starts at the focused widget, so a text widget's own action
//! answers before the application's. Two routes do not pass through the
//! widget at all, and there the application owes it an answer: a menu row or
//! a toolbar button, whose intent starts in the chrome, and a widget that
//! refused its history (a forward-only writing mode), which passes the intent
//! on rather than letting it reach the application's own history.
//!
//! It cannot produce one by itself. It can recognise the surfaces it built and
//! kept a handle on, and it is blind to the rest: a rename box in a table cell,
//! a search field, a text input inside a dialog it did not write. An application
//! that guesses gets it exactly backwards — Ctrl+Z in a rename box undoes
//! something else entirely, which is worse than not having the feature.
//!
//! Maintaining a list of every text widget in the application is not a fix: it
//! is correct on the day it is written and wrong the first time someone adds a
//! field. The framework already knows which widget has focus and which widgets
//! edit text, so it is the only place the question can be answered *completely*.
//!
//! # What implementors get
//!
//! Every text widget registers itself with [`BuildContext::register_text_surface`],
//! and the registration is torn down with the widget exactly as a global action
//! is. A host then asks [`WidgetTree::focused_text_surface`] and either drives it
//! or — knowing one exists — steps aside and lets the widget keep its own keys.
//!
//! # An empty history can pass the command on
//!
//! By default the focused text widget answers Undo and Redo whether or not it
//! has anything to step through, so an application's own `edit.undo` action is
//! reached only from a menu, or where no text widget has focus. An application
//! whose Undo deliberately falls back to a wider history when the caret's own
//! is exhausted — and says so, in a menu row naming what it will undo — turns
//! on [`TextSurfaces::set_empty_history_passes_on`]: a text widget with nothing
//! to undo then declines the command, and the intent climbs to the
//! application's action exactly as it does from a refused history. Off by
//! default, because an application that never announces the fallback would
//! have Ctrl+Z in an empty search field undo something the user is not looking
//! at.
//!
//! [`BuildContext::register_text_surface`]: crate::build_context::BuildContext::register_text_surface
//! [`WidgetTree::focused_text_surface`]: crate::widget_tree::WidgetTree::focused_text_surface

use std::cell::{Cell, RefCell};
use std::rc::Rc;

use crate::signal::Signal;
use crate::widget::EventContext;
use crate::widget_id::WidgetId;

/// A widget that edits text, seen through the commands a host may need to
/// invoke on it from outside — a menu row, a routed shortcut, an assistive
/// technology.
///
/// Object-safe on purpose: a host holds `Rc<dyn TextSurface>` for whichever
/// widget has focus, without knowing which kind it is.
pub trait TextSurface {
    /// Is there anything in this surface's own history to step back through?
    fn can_undo(&self) -> bool;
    /// Is there anything to step forward into?
    fn can_redo(&self) -> bool;
    fn undo(&self);
    fn redo(&self);

    /// Is this surface refusing to step through its history at all?
    ///
    /// Distinct from having nothing to undo, and a host must treat them
    /// differently: an empty history may be a reason to look elsewhere, a
    /// refusal is not. Applications impose modes — a "forbid erasing" writing
    /// game, a read-only review pass — and a routed Undo that quietly went
    /// somewhere else would defeat them.
    fn history_frozen(&self) -> bool {
        false
    }

    /// Is any text selected right now?
    fn has_selection(&self) -> bool;
    /// Does this surface refuse edits? Cut and Paste are meaningless when it does.
    fn is_read_only(&self) -> bool;
    /// May its contents be copied at all? A password field says no.
    fn allows_copy(&self) -> bool;

    fn cut(&self, ctx: &EventContext<'_>);
    fn copy(&self, ctx: &EventContext<'_>);
    fn paste(&self, ctx: &EventContext<'_>);
    /// Paste stripped of formatting. A surface with no formatting to strip
    /// should do a plain paste rather than nothing.
    fn paste_plain(&self, ctx: &EventContext<'_>);
    fn select_all(&self);
}

/// A cloneable view of one tree's registered text surfaces.
///
/// Taken once, with [`BuildContext::text_surfaces`], and held by whatever needs
/// to ask the question later — a view-model refreshed from a frame tick has no
/// `&WidgetTree` to consult, which is precisely when it needs the answer.
///
/// [`BuildContext::text_surfaces`]: crate::build_context::BuildContext::text_surfaces
#[derive(Clone)]
pub struct TextSurfaces {
    entries: Rc<RefCell<Vec<(WidgetId, Rc<dyn TextSurface>)>>>,
    focused: Signal<Option<WidgetId>>,
    empty_history_passes_on: Rc<Cell<bool>>,
}

impl std::fmt::Debug for TextSurfaces {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("TextSurfaces")
            .field("registered", &self.entries.borrow().len())
            .field("focused_is_text", &self.focused_is_text_surface())
            .field("empty_history_passes_on", &self.empty_history_passes_on())
            .finish()
    }
}

impl TextSurfaces {
    pub(crate) fn new(focused: Signal<Option<WidgetId>>) -> Self {
        Self {
            entries: Rc::new(RefCell::new(Vec::new())),
            focused,
            empty_history_passes_on: Rc::new(Cell::new(false)),
        }
    }

    /// Record that `owner` edits text, replacing any previous registration from
    /// the same widget so a rebuild re-points rather than accumulating.
    pub(crate) fn insert(&self, owner: WidgetId, surface: Rc<dyn TextSurface>) {
        let mut entries = self.entries.borrow_mut();
        entries.retain(|(id, _)| *id != owner);
        entries.push((owner, surface));
    }

    /// Forget `owner`'s registration — on its rebuild or destroy.
    pub(crate) fn remove(&self, owner: WidgetId) {
        self.entries.borrow_mut().retain(|(id, _)| *id != owner);
    }

    /// The text-editing widget that currently holds the keyboard focus.
    ///
    /// `None` when focus is elsewhere — or nowhere — which is exactly what a
    /// host needs in order to know that a text chord is safe to route itself.
    pub fn focused(&self) -> Option<Rc<dyn TextSurface>> {
        let focused = self.focused.get()?;
        self.entries
            .borrow()
            .iter()
            .find(|(id, _)| *id == focused)
            .map(|(_, s)| Rc::clone(s))
    }

    /// Is the keyboard focus inside a widget that edits text? The cheap half of
    /// [`focused`](Self::focused), for a host that only needs to decide whether
    /// to step aside.
    pub fn focused_is_text_surface(&self) -> bool {
        self.focused().is_some()
    }

    /// Does the widget registered under `owner` refuse edits?
    ///
    /// `false` for a widget that edits nothing — the question is only asked of
    /// text surfaces, and a node that is not one is not read-only, it is simply
    /// not text. Read by the hit-test slop pass, which must never re-attribute
    /// a press to a surface that would ignore it.
    pub fn is_read_only(&self, owner: WidgetId) -> bool {
        self.entries
            .borrow()
            .iter()
            .find(|(id, _)| *id == owner)
            .map(|(_, s)| s.is_read_only())
            .unwrap_or(false)
    }

    /// Make every text widget of this tree decline Undo when it has nothing to
    /// undo, and Redo when it has nothing to redo, so the intent goes on to an
    /// ancestor's action — the application's own history — instead of stopping
    /// at a widget that would do nothing with it. See the
    /// [module documentation](self#an-empty-history-can-pass-the-command-on).
    ///
    /// Off by default. Applies to `RichTextEditor`, `TextInputField` and the
    /// fields built on it, and `CodeEditor`, from the next command they
    /// receive; set it once, from the root's `build`. The widgets ask their
    /// document at the moment the command runs, never a cached
    /// [`can_undo`](TextSurface::can_undo), so a keystroke typed a moment
    /// earlier is always undone where it was typed.
    pub fn set_empty_history_passes_on(&self, on: bool) {
        self.empty_history_passes_on.set(on);
    }

    /// Whether a text widget with nothing to undo (or redo) passes the command
    /// on. See [`set_empty_history_passes_on`](Self::set_empty_history_passes_on).
    pub fn empty_history_passes_on(&self) -> bool {
        self.empty_history_passes_on.get()
    }

    /// The signal to react to. A host mirroring "can undo" into a menu row
    /// re-reads when focus moves.
    pub fn focus_signal(&self) -> Signal<Option<WidgetId>> {
        self.focused.clone()
    }
}