blockworx/

gesture.rs

//! The gesture bracket: what a gesture is, stated once.
//!
//! Everything written between [`Gesture::open`] and [`seal`] lands in one
//! commit — the solve rider completes it, the seal decides whether there is
//! anything to say, and the repo folds it.

use blockworx_doc::commit::{Commit, CommitBuilder};
use blockworx_doc::document::{DocIndex, Document, IndexedDocument};
use blockworx_doc::id::{Allocator, Id, IdKind};
use blockworx_doc::opcode::OpCodes;

use crate::edit::describe::Label;
use crate::path::BlockPath;
use crate::presentation::Presentation;
use crate::widget::drawing::Drawing;
use blockworx_doc::repo::Repo;
use blockworx_store::doc::Writability;

/// The ops a gesture has authored, and the document they imply.
///
/// The prediction is why this is a type rather than a bare [`CommitBuilder`].
/// The repo's document only advances at submit, so a gesture reading it
/// would not see its own writes: a block placed and immediately
/// renamed reads as absent, which is what the four `Arming` tool states used
/// to defer around. [`Gesture::author`] is the only way in, and it folds
/// what the gesture has said so far onto the base — so the next read, in
/// this same frame, sees it.
pub struct Gesture {
    ops: CommitBuilder,
    /// What this gesture is called before it has authored anything —
    /// finished at the seal, where the ops say what it acted on.
    label: Label,
    /// The base with [`Self::ops`] folded on. `None` while the gesture has
    /// authored nothing, because then the base already *is* the prediction —
    /// an idle frame pays neither the fold nor the index rebuild.
    staged: Option<Staged>,
    /// The ids this gesture has handed out, beside the document's own
    /// marks. A mint that never becomes a `Create` still raises this, so
    /// two mints of one kind cannot collide inside a gesture; an abandoned
    /// gesture takes its marks with it, which costs nothing because it
    /// created nothing.
    ids: Allocator,
    /// Whether the session behind this sink may write at all. Carried here
    /// because this is the write door: a read-only session's gesture
    /// declines in [`Self::author`], and the tools read the same answer
    /// through [`Drawing::authoring`](crate::widget::drawing::Drawing::authoring)
    /// to decide what to offer in the first place.
    writability: Writability,
}

struct Staged {
    doc: Document,
    index: DocIndex,
}

impl Gesture {
    /// Open a gesture under its semantic label.
    pub fn open(label: Label, writability: Writability) -> Self {
        Self {
            // The builder's own label never reaches a commit: the seal
            // replaces it with what the ops turned out to describe.
            ops: CommitBuilder::new(String::new()),
            label,
            staged: None,
            ids: Allocator::default(),
            writability,
        }
    }

    /// A gesture between gestures, and the sink a read pass is handed.
    /// Nothing writes into it — every write opens its own labelled one — so
    /// neither this label nor its writability reaches a commit.
    pub fn idle() -> Self {
        Self::open(Label::verb("Idle"), Writability::Writable)
    }

    pub fn writability(&self) -> Writability {
        self.writability
    }

    pub fn ops(&self) -> &[OpCodes] {
        self.ops.ops()
    }

    /// The allocator an emitter whose id count is data-dependent (paste)
    /// mints from: this gesture's marks raised to the prediction's, so
    /// nothing it has authored can be minted twice.
    pub fn ids(&self, base: &Document) -> Allocator {
        let mut ids = self.ids;
        ids.raise_to(&self.prediction(base).ids());
        ids
    }

    /// A fresh id for a setter that mints one.
    pub fn mint<K: IdKind>(&mut self, base: &Document) -> Id<K> {
        self.ids = self.ids(base);
        self.ids.mint()
    }

    /// The document as this gesture has left it: the base until it writes.
    fn prediction<'v>(&'v self, base: &'v Document) -> &'v Document {
        self.staged.as_ref().map_or(base, |staged| &staged.doc)
    }

    /// The document this gesture reads: `base` with its own writes folded
    /// on. Identical to `base` until it writes.
    pub fn view<'v>(&'v self, base: IndexedDocument<'v>) -> IndexedDocument<'v> {
        self.staged
            .as_ref()
            .and_then(|staged| staged.index.view_of(&staged.doc))
            .unwrap_or(base)
    }

    /// The one write door. `emit` is handed the document as this gesture has
    /// left it and the sink to author into; whatever it pushes advances the
    /// prediction before the call returns, so no caller can read a document
    /// that predates its own edit.
    ///
    /// `what` names the edit for the mutation log (`RUST_LOG=edit=debug`),
    /// which narrates here rather than at each setter: authoring without
    /// narrating would mean calling this without an argument.
    pub fn author(
        &mut self,
        base: IndexedDocument<'_>,
        what: &'static str,
        emit: impl FnOnce(&IndexedDocument<'_>, &mut CommitBuilder),
    ) {
        if self.writability == Writability::ReadOnly {
            tracing::debug!(target: "edit", edit = what, "withheld: the session is read-only");
            return;
        }
        let before = self.ops.ops().len();
        {
            // Disjoint fields: the view borrows the staged prediction, the
            // sink is the builder beside it.
            let view = self
                .staged
                .as_ref()
                .and_then(|staged| staged.index.view_of(&staged.doc))
                .unwrap_or(base);
            emit(&view, &mut self.ops);
        }
        let authored: Vec<String> = self.ops.ops()[before..]
            .iter()
            .map(OpCodes::narrate)
            .collect();
        if authored.is_empty() {
            // A named setter that found nothing to change: the emitters drop
            // non-edits, which is what keeps an abandoned gesture empty.
            tracing::debug!(target: "edit", edit = what, "declined");
            return;
        }
        tracing::debug!(target: "edit", edit = what, ops = ?authored, "authored");
        self.restage(base.doc);
    }

    /// Re-fold the whole gesture onto `base`. Whole, not incremental: op
    /// order within a commit is free for references (a pin may precede its
    /// owner's create), so a half-gesture can fail a validation the finished
    /// one passes.
    fn restage(&mut self, base: &Document) {
        let staged = Commit::new(String::new(), self.ops.ops().to_vec());
        match base.try_apply(&staged) {
            Ok(doc) => {
                let index = DocIndex::of(&doc);
                self.staged = Some(Staged { doc, index });
            }
            // The refusal the submission will report. Keeping the previous
            // prediction rather than dropping to the base leaves the user
            // looking at what they drew until the seal says otherwise.
            Err(refusal) => {
                tracing::error!("the gesture's own prediction was refused: {refusal}");
            }
        }
    }

    /// Seal the gesture under `label` and leave a fresh idle one in its
    /// place. `None` when nothing was authored, which is what makes an
    /// abandoned drag a non-event.
    pub(crate) fn seal(&mut self, label: String) -> Option<Commit> {
        let fresh = Self::open(Label::verb("Idle"), self.writability);
        std::mem::replace(self, fresh)
            .ops
            .seal()
            .map(|commit| commit.relabelled(label))
    }
}

/// The current scope, over the gesture's view of the repo's document.
pub fn drawing<'a>(
    repo: &'a Repo,
    index: &'a mut DocIndex,
    path: &'a BlockPath,
    presentation: &'a mut Presentation,
    gesture: &'a mut Gesture,
) -> Drawing<'a> {
    let base = index.view(repo.document());
    Drawing::new(base, path, presentation, gesture)
}

/// Finish the gesture: run the solve rider over what it wrote and seal it,
/// leaving `gesture` open on a fresh idle one. `None` when it authored
/// nothing.
pub fn seal(
    document: &Document,
    index: &mut DocIndex,
    path: &BlockPath,
    presentation: &Presentation,
    gesture: &mut Gesture,
) -> Option<Commit> {
    if gesture.ops().is_empty() {
        return None;
    }
    // Described before the rider runs: the wires it re-solves are a
    // consequence of the edit, not the thing the user did, and counting
    // them would turn "move a block" into "5 shapes".
    let label = gesture
        .label
        .describing(&index.view(document), gesture.ops());
    let base = index.view(document);
    gesture.author(base, "solve_rider", |indexed, sink| {
        crate::widget::routing::solve_rider(indexed, path, presentation, sink);
    });
    gesture.seal(label)
}