Chapter 7: Block Editor

April 13, 2026 · View on GitHub

Welcome to Chapter 7: Block Editor. In this part of Athens Research: Deep Dive Tutorial, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

The block editor is the center of Athens' UX and data model.

Core Editor Behaviors

  • Enter creates sibling blocks.
  • Tab/Shift-Tab changes hierarchy depth.
  • Backspace at start merges or lifts blocks.
  • [[...]] creates structured references.

Editor State Model

Track editor state separately from persisted graph state:

  • cursor/selection range
  • composition state (IME, pending transforms)
  • active command palette context

Command Handling Pattern

key input -> editor command -> local state update -> persistence effect

Quality Checklist

  • Cursor behavior is deterministic across nested blocks.
  • Undo/redo spans structural edits, not only text deltas.
  • Reference creation preserves block UUID identity.

Summary

You can now reason about Athens editor behavior and command pipelines.

Next: Chapter 8: Rich Text

What Problem Does This Solve?

Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for input, editor, command so behavior stays predictable as complexity grows.

In practical terms, this chapter helps you avoid three common failures:

  • coupling core logic too tightly to one implementation path
  • missing the handoff boundaries between setup, execution, and validation
  • shipping changes without clear rollback or observability strategy

After working through this chapter, you should be able to reason about Chapter 7: Block Editor as an operating subsystem inside Athens Research: Deep Dive Tutorial, with explicit contracts for inputs, state transitions, and outputs.

Use the implementation notes around local, state, update as your checklist when adapting these patterns to your own repository.

How it Works Under the Hood

Under the hood, Chapter 7: Block Editor usually follows a repeatable control path:

  1. Context bootstrap: initialize runtime config and prerequisites for input.
  2. Input normalization: shape incoming data so editor receives stable contracts.
  3. Core execution: run the main logic branch and propagate intermediate state through command.
  4. Policy and safety checks: enforce limits, auth scopes, and failure boundaries.
  5. Output composition: return canonical result payloads for downstream consumers.
  6. Operational telemetry: emit logs/metrics needed for debugging and performance tuning.

When debugging, walk this sequence in order and confirm each stage has explicit success/failure conditions.

Source Walkthrough

Use the following upstream sources to verify implementation details while reading this chapter:

  • Athens Research Why it matters: authoritative reference on Athens Research (github.com).

Suggested trace strategy:

  • search upstream code for input and editor to map concrete implementation paths
  • compare docs claims against actual runtime/config code before reusing patterns in production

Chapter Connections

Depth Expansion Playbook

Source Code Walkthrough

src/cljs/athens/views/blocks/editor.cljs

The block editor implementation is in src/cljs/athens/views/blocks/editor.cljs. This file handles keystroke events, cursor management, block splitting/merging, and indentation — the core outliner behaviors described in Chapter 7. The keyboard shortcut dispatch logic shows how editing commands map to Re-frame events that modify the Datascript graph.