edit_intent.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/timeline/command.hpp>
#include <pulp/timeline/document_session.hpp>
#include <pulp/timeline_editor/sequencer_ui_host.hpp>
 
#include <optional>
#include <span>
#include <utility>
 
namespace pulp::timeline_editor {
 
namespace detail {
class EditGestureIdentityIssueTestAccess;
}


enum class EditIntentKind : std::uint8_t {
    Draw,   
    Erase,  
    Move,   
    Resize, 
};

struct EditIntent {
    EditIntentKind kind = EditIntentKind::Move;
    timeline::GesturePhase phase = timeline::GesturePhase::Single;
 
    timeline::ItemId sequence_id;
    timeline::ItemId track_id;
    timeline::ItemId clip_id;

    std::optional<timeline::ClipTimeRange> expected_range;
    std::optional<timeline::ClipTimeRange> replacement_range;
    std::optional<timeline::Clip> clip;
 
    bool operator==(const EditIntent& other) const noexcept;
};

enum class NoteEditIntentKind : std::uint8_t {
    Insert,      
    Erase,       
    Move,        
    Resize,      
    SetVelocity, 
};

struct NoteEditIntent {
    NoteEditIntentKind kind = NoteEditIntentKind::Move;
    timeline::GesturePhase phase = timeline::GesturePhase::Single;
 
    timeline::ItemId sequence_id;
    timeline::ItemId track_id;
    timeline::ItemId clip_id;
 
    std::optional<timeline::NoteEvent> expected;
    std::optional<timeline::NoteEvent> replacement;
 
    bool operator==(const NoteEditIntent& other) const noexcept;
};

std::optional<timeline::ModelError>
validate_note_edit_intent(const NoteEditIntent& intent) noexcept;

class ValidatedNoteEditIntent {
  public:
    static runtime::Result<ValidatedNoteEditIntent, timeline::ModelError>
    create(NoteEditIntent intent) noexcept;

    const NoteEditIntent& value() const noexcept {
        return value_;
    }
 
    bool operator==(const ValidatedNoteEditIntent& other) const noexcept {
        return value_ == other.value_;
    }
 
  private:
    explicit ValidatedNoteEditIntent(NoteEditIntent intent) noexcept : value_(std::move(intent)) {}
 
    NoteEditIntent value_;
};
 
enum class NoteLoweringError : std::uint8_t;

using NoteEditIntentHost = SequencerUiHostT<ValidatedNoteEditIntent>;

struct EditIntentIdentity {
    timeline::TransactionId transaction_id;
    timeline::DocumentRevision expected_revision;
    timeline::CommandId command_id;
    std::optional<timeline::UndoGroupId> undo_group;
};

enum class EditGestureIdentityState : std::uint8_t {
    AwaitingBegin,
    Open,
    Closed,
    Exhausted,
};

enum class EditGestureIdentityError : std::uint8_t {
    InvalidWriter,
    WriterMismatch,
    InvalidPhase,
    GestureClosed,
    IdentityExhausted,
    IdentityPending,
    ForeignOrStaleIssue,
    IntentLoweringFailed,
    SubmissionResultMismatch,
};

struct EditGestureSubmitOutcome {
    runtime::Result<timeline::CommitResult, timeline::TransactionError> document_result;
    EditGestureIdentityState state = EditGestureIdentityState::AwaitingBegin;
};

struct EditGestureSubmitError {
    EditGestureIdentityError code = EditGestureIdentityError::ForeignOrStaleIssue;
    std::optional<timeline::ModelError> model_error;
    std::optional<timeline::CommitResult> commit_result;
    std::optional<NoteLoweringError> note_lowering_error;
};
 
class EditGestureIdentityAllocator;

class EditGestureIdentityIssue {
  public:
    EditGestureIdentityIssue(const EditGestureIdentityIssue&) = delete;
    EditGestureIdentityIssue& operator=(const EditGestureIdentityIssue&) = delete;
    EditGestureIdentityIssue(EditGestureIdentityIssue&& other) noexcept
        : identity_(std::exchange(other.identity_, {})),
          phase_(std::exchange(other.phase_, timeline::GesturePhase::Single)),
          provenance_(std::exchange(other.provenance_, {})) {}
    EditGestureIdentityIssue& operator=(EditGestureIdentityIssue&&) = delete;

    timeline::GesturePhase phase() const noexcept {
        return phase_;
    }
 
  private:
    friend class EditGestureIdentityAllocator;
    friend class detail::EditGestureIdentityIssueTestAccess;
    EditGestureIdentityIssue(EditIntentIdentity identity, timeline::GesturePhase phase,
                             timeline::WriterToken::Provenance provenance) noexcept
        : identity_(std::move(identity)), phase_(phase), provenance_(provenance) {}
 
    runtime::Result<timeline::Transaction, timeline::ModelError> lower(EditIntent intent) const;
    runtime::Result<timeline::Transaction, NoteLoweringError>
    lower(ValidatedNoteEditIntent intent,
          std::span<const timeline::NoteEvent> current_notes) const;
 
    void invalidate() noexcept {
        identity_ = {};
        phase_ = timeline::GesturePhase::Single;
        provenance_ = {};
    }
 
    EditIntentIdentity identity_;
    timeline::GesturePhase phase_ = timeline::GesturePhase::Single;
    timeline::WriterToken::Provenance provenance_;
};

class EditGestureIdentityAllocator {
  public:
    static runtime::Result<EditGestureIdentityAllocator, EditGestureIdentityError>
    create(timeline::WriterToken& writer) noexcept {
        const auto provenance = writer.provenance();
        if (!provenance.valid())
            return runtime::Result<EditGestureIdentityAllocator, EditGestureIdentityError>(
                runtime::Err(EditGestureIdentityError::InvalidWriter));
 
        const auto undo_group = writer.allocate_undo_group_id();
        if (!undo_group.valid())
            return runtime::Result<EditGestureIdentityAllocator, EditGestureIdentityError>(
                runtime::Err(EditGestureIdentityError::IdentityExhausted));
 
        return runtime::Result<EditGestureIdentityAllocator, EditGestureIdentityError>(
            runtime::Ok(EditGestureIdentityAllocator(provenance, undo_group)));
    }
 
    EditGestureIdentityAllocator(const EditGestureIdentityAllocator&) = delete;
    EditGestureIdentityAllocator& operator=(const EditGestureIdentityAllocator&) = delete;
    EditGestureIdentityAllocator(EditGestureIdentityAllocator&& other) noexcept
        : provenance_(std::exchange(other.provenance_, {})),
          undo_group_(std::exchange(other.undo_group_, {})),
          state_(std::exchange(other.state_, EditGestureIdentityState::Closed)),
          pending_(std::exchange(other.pending_, false)),
          pending_transaction_(std::exchange(other.pending_transaction_, {})),
          pending_revision_(std::exchange(other.pending_revision_, {})),
          pending_command_(std::exchange(other.pending_command_, {})),
          pending_phase_(std::exchange(other.pending_phase_, timeline::GesturePhase::Single)) {}
    EditGestureIdentityAllocator& operator=(EditGestureIdentityAllocator&&) = delete;

    runtime::Result<EditGestureIdentityIssue, EditGestureIdentityError>
    issue(timeline::WriterToken& writer, timeline::DocumentRevision expected_revision,
          timeline::GesturePhase phase) noexcept {
        if (state_ == EditGestureIdentityState::Closed)
            return issue_error(EditGestureIdentityError::GestureClosed);
        if (state_ == EditGestureIdentityState::Exhausted)
            return issue_error(EditGestureIdentityError::IdentityExhausted);
        if (pending_)
            return issue_error(EditGestureIdentityError::IdentityPending);
        if (!writer.provenance().valid())
            return issue_error(EditGestureIdentityError::InvalidWriter);
        if (writer.provenance() != provenance_)
            return issue_error(EditGestureIdentityError::WriterMismatch);
        if (!phase_permitted(phase))
            return issue_error(EditGestureIdentityError::InvalidPhase);
 
        const auto transaction_id = writer.allocate_transaction_id();
        if (!transaction_id.valid()) {
            state_ = EditGestureIdentityState::Exhausted;
            return issue_error(EditGestureIdentityError::IdentityExhausted);
        }
 
        const auto command_id = writer.allocate_command_id();
        if (!command_id.valid()) {
            state_ = EditGestureIdentityState::Exhausted;
            return issue_error(EditGestureIdentityError::IdentityExhausted);
        }
 
        EditIntentIdentity identity{transaction_id, expected_revision, command_id, undo_group_};
        pending_ = true;
        pending_transaction_ = transaction_id;
        pending_revision_ = expected_revision;
        pending_command_ = command_id;
        pending_phase_ = phase;
        return runtime::Result<EditGestureIdentityIssue, EditGestureIdentityError>(
            runtime::Ok(EditGestureIdentityIssue(std::move(identity), phase, provenance_)));
    }

    runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>
    submit(timeline::DocumentSession& session, timeline::WriterToken& writer,
           EditGestureIdentityIssue&& issue, EditIntent intent) {
        if (!matches_pending(issue))
            return submit_error(EditGestureIdentityError::ForeignOrStaleIssue);
        if (!writer.provenance().valid())
            return submit_error(EditGestureIdentityError::InvalidWriter);
        if (writer.provenance() != provenance_)
            return submit_error(EditGestureIdentityError::WriterMismatch);
 
        auto transaction = issue.lower(std::move(intent));
        if (!transaction)
            return lowering_error(transaction.error());
 
        return submit_lowered(session, writer, issue, std::move(*transaction));
    }

    runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>
    submit(timeline::DocumentSession& session, timeline::WriterToken& writer,
           EditGestureIdentityIssue&& issue, ValidatedNoteEditIntent intent,
           std::span<const timeline::NoteEvent> current_notes) {
        if (!matches_pending(issue))
            return submit_error(EditGestureIdentityError::ForeignOrStaleIssue);
        if (!writer.provenance().valid())
            return submit_error(EditGestureIdentityError::InvalidWriter);
        if (writer.provenance() != provenance_)
            return submit_error(EditGestureIdentityError::WriterMismatch);
 
        auto transaction = issue.lower(std::move(intent), current_notes);
        if (!transaction)
            return note_lowering_error(transaction.error());
 
        return submit_lowered(session, writer, issue, std::move(*transaction));
    }

    timeline::UndoGroupId undo_group() const noexcept {
        return undo_group_;
    }

    EditGestureIdentityState state() const noexcept {
        return state_;
    }

    bool has_pending_identity() const noexcept {
        return pending_;
    }
 
  private:
    EditGestureIdentityAllocator(timeline::WriterToken::Provenance provenance,
                                 timeline::UndoGroupId undo_group) noexcept
        : provenance_(provenance), undo_group_(undo_group) {}
 
    bool phase_permitted(timeline::GesturePhase phase) const noexcept {
        if (state_ == EditGestureIdentityState::AwaitingBegin)
            return phase == timeline::GesturePhase::Begin;
        return phase == timeline::GesturePhase::Update || phase == timeline::GesturePhase::End ||
               phase == timeline::GesturePhase::Cancel;
    }
 
    bool matches_pending(const EditGestureIdentityIssue& issue) const noexcept {
        const auto& identity = issue.identity_;
        return pending_ && issue.provenance_ == provenance_ && issue.phase_ == pending_phase_ &&
               identity.transaction_id == pending_transaction_ &&
               identity.expected_revision == pending_revision_ &&
               identity.command_id == pending_command_ && identity.undo_group == undo_group_;
    }
 
    static EditGestureIdentityState committed_state_after(timeline::GesturePhase phase) noexcept {
        if (phase == timeline::GesturePhase::Begin || phase == timeline::GesturePhase::Update)
            return EditGestureIdentityState::Open;
        return EditGestureIdentityState::Closed;
    }
 
    runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>
    submit_lowered(timeline::DocumentSession& session, timeline::WriterToken& writer,
                   EditGestureIdentityIssue& issue, timeline::Transaction transaction) {
        const auto phase = pending_phase_;
        const auto command = pending_command_;
        auto document_result = session.submit(writer, std::move(transaction));
        issue.invalidate();
        clear_pending();
        if (document_result) {
            if (document_result->applied_commands.size() != 1 ||
                document_result->applied_commands.front() != command ||
                !session.is_current_publication(*document_result)) {
                if (phase == timeline::GesturePhase::Begin)
                    state_ = session.is_gesture_open(provenance_, undo_group_)
                                 ? EditGestureIdentityState::Open
                                 : EditGestureIdentityState::AwaitingBegin;
                return submission_result_error(std::move(*document_result));
            }
            state_ = committed_state_after(phase);
        }
        return runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>(runtime::Ok(
            EditGestureSubmitOutcome{std::move(document_result), state_}));
    }
 
    void clear_pending() noexcept {
        pending_ = false;
        pending_transaction_ = {};
        pending_revision_ = {};
        pending_command_ = {};
        pending_phase_ = timeline::GesturePhase::Single;
    }
 
    static runtime::Result<EditGestureIdentityIssue, EditGestureIdentityError>
    issue_error(EditGestureIdentityError error) noexcept {
        return runtime::Result<EditGestureIdentityIssue, EditGestureIdentityError>(
            runtime::Err(error));
    }
 
    static runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>
    submit_error(EditGestureIdentityError error) {
        return runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>(
            runtime::Err(EditGestureSubmitError{error, std::nullopt, std::nullopt,
                                                std::nullopt}));
    }
 
    static runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>
    lowering_error(timeline::ModelError error) {
        return runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>(runtime::Err(
            EditGestureSubmitError{EditGestureIdentityError::IntentLoweringFailed, error,
                                   std::nullopt, std::nullopt}));
    }
 
    static runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>
    note_lowering_error(NoteLoweringError error) {
        return runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>(runtime::Err(
            EditGestureSubmitError{EditGestureIdentityError::IntentLoweringFailed,
                                   std::nullopt, std::nullopt, error}));
    }
 
    static runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>
    submission_result_error(timeline::CommitResult result) {
        return runtime::Result<EditGestureSubmitOutcome, EditGestureSubmitError>(runtime::Err(
            EditGestureSubmitError{EditGestureIdentityError::SubmissionResultMismatch,
                                   std::nullopt, std::move(result), std::nullopt}));
    }
 
    timeline::WriterToken::Provenance provenance_;
    timeline::UndoGroupId undo_group_;
    EditGestureIdentityState state_ = EditGestureIdentityState::AwaitingBegin;
    bool pending_ = false;
    timeline::TransactionId pending_transaction_;
    timeline::DocumentRevision pending_revision_;
    timeline::CommandId pending_command_;
    timeline::GesturePhase pending_phase_ = timeline::GesturePhase::Single;
};

using EditIntentHost = SequencerUiHostT<EditIntent>;

enum class NoteLoweringError : std::uint8_t {
    ContinuousGestureUnsupported,
    DuplicateNoteIdentity,
    NoteNotInClip,
    ExpectedNoteMismatch,
    InvalidIdentity,
};

runtime::Result<timeline::Transaction, NoteLoweringError>
lower_note_edit_intent(const ValidatedNoteEditIntent& intent,
                       std::span<const timeline::NoteEvent> current_notes,
                       const EditIntentIdentity& identity);

runtime::Result<timeline::Transaction, timeline::ModelError>
lower_edit_intent(const EditIntent& intent, const EditIntentIdentity& identity);
 
inline runtime::Result<timeline::Transaction, timeline::ModelError>
EditGestureIdentityIssue::lower(EditIntent intent) const {
    intent.phase = phase_;
    return lower_edit_intent(intent, identity_);
}
 
inline runtime::Result<timeline::Transaction, NoteLoweringError>
EditGestureIdentityIssue::lower(ValidatedNoteEditIntent intent,
                                std::span<const timeline::NoteEvent> current_notes) const {
    auto value = intent.value();
    value.phase = phase_;
    auto authoritative = ValidatedNoteEditIntent::create(std::move(value));
    if (!authoritative)
        return runtime::Result<timeline::Transaction, NoteLoweringError>(
            runtime::Err(NoteLoweringError::InvalidIdentity));
    return lower_note_edit_intent(*authoritative, current_notes, identity_);
}

 
} // namespace pulp::timeline_editor