Skip to content

06-block-editor.md

Latest commit

 

History

History
280 lines (201 loc) · 8.26 KB

06-block-editor.md

File metadata and controls

280 lines (201 loc) · 8.26 KB
layout default
title Chapter 6: Block Editor
nav_order 6
has_children false
parent Logseq Knowledge Management

Chapter 6: Block Editor

Welcome to Chapter 6: Block Editor. In this part of Logseq: 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 where text editing, structural hierarchy, and graph references converge.

Core Interaction Model

  • indentation/outdent controls hierarchy
  • inline references create graph edges
  • keyboard-first commands optimize authoring speed
  • slash commands trigger structured actions/templates

Engineering Challenges

Challenge Why It Is Hard
nested selection behavior text + structure edits overlap
undo/redo correctness must restore both text and tree shape
low-latency updates large pages can trigger heavy recalculation
IME/multilingual editing composition events complicate key handling

Reliability Patterns

  • incremental state updates for large documents
  • deterministic edit transactions
  • robust cursor restoration after structural edits
  • regression tests for keyboard workflows

UX Quality Signals

  • predictable tab/shift-tab behavior
  • no cursor jumps during auto-formatting
  • stable performance in deeply nested pages

Summary

You can now analyze editor behavior as transaction-safe graph and text mutations.

Next: Chapter 7: Bi-Directional Links

What Problem Does This Solve?

Most teams struggle here because the hard part is not writing more code, but deciding clear boundaries for core abstractions in this chapter 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 6: Block Editor as an operating subsystem inside Logseq: Deep Dive Tutorial, with explicit contracts for inputs, state transitions, and outputs.

Use the implementation notes around execution and reliability details as your checklist when adapting these patterns to your own repository.

How it Works Under the Hood

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

  1. Context bootstrap: initialize runtime config and prerequisites for core component.
  2. Input normalization: shape incoming data so execution layer receives stable contracts.
  3. Core execution: run the main logic branch and propagate intermediate state through state model.
  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:

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

Suggested trace strategy:

  • search upstream code for Block 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

libs/src/helpers.ts

The cleanInjectedUI function in libs/src/helpers.ts handles a key part of this chapter's functionality:

}

export function cleanInjectedUI(id: string) {
  if (!injectedUIEffects.has(id)) return
  const clean = injectedUIEffects.get(id)
  try {
    clean()
  } catch (e) {
    console.warn('[CLEAN Injected UI] ', id, e)
  }
}

export function cleanInjectedScripts(this: PluginLocal) {
  const scripts = document.head.querySelectorAll(`script[data-ref=${this.id}]`)

  scripts?.forEach((it) => it.remove())
}

export function transformableEvent(target: HTMLElement, e: Event) {
  const obj: any = {}

  if (target) {
    obj.type = e.type

    const ds = target.dataset
    const FLAG_RECT = 'rect'

    ;['value', 'id', 'className', 'dataset', FLAG_RECT].forEach((k) => {
      let v: any

      switch (k) {
        case FLAG_RECT:

This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.

libs/src/helpers.ts

The cleanInjectedScripts function in libs/src/helpers.ts handles a key part of this chapter's functionality:

}

export function cleanInjectedScripts(this: PluginLocal) {
  const scripts = document.head.querySelectorAll(`script[data-ref=${this.id}]`)

  scripts?.forEach((it) => it.remove())
}

export function transformableEvent(target: HTMLElement, e: Event) {
  const obj: any = {}

  if (target) {
    obj.type = e.type

    const ds = target.dataset
    const FLAG_RECT = 'rect'

    ;['value', 'id', 'className', 'dataset', FLAG_RECT].forEach((k) => {
      let v: any

      switch (k) {
        case FLAG_RECT:
          if (!ds.hasOwnProperty(FLAG_RECT)) return
          v = target.getBoundingClientRect().toJSON()
          break
        default:
          v = target[k]
      }

      if (typeof v === 'object') {
        v = { ...v }
      }

This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.

libs/src/helpers.ts

The transformableEvent function in libs/src/helpers.ts handles a key part of this chapter's functionality:

        const msgType = trigger.dataset[`on${ucFirst(type)}`]
        if (msgType)
          pl.caller?.callUserModel(msgType, transformableEvent(trigger, e))
        if (preventDefault?.toLowerCase() === 'true') e.preventDefault()
      },
      false
    )
  })

  // callback
  initialCallback?.({ el, float })

  teardownUI = () => {
    disposeFloat?.()
    injectedUIEffects.delete(id)
    target!.removeChild(el)
  }

  injectedUIEffects.set(id, teardownUI)
  return teardownUI
}

export function cleanInjectedUI(id: string) {
  if (!injectedUIEffects.has(id)) return
  const clean = injectedUIEffects.get(id)
  try {
    clean()
  } catch (e) {
    console.warn('[CLEAN Injected UI] ', id, e)
  }
}

This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.

libs/src/helpers.ts

The injectTheme function in libs/src/helpers.ts handles a key part of this chapter's functionality:

}

export function injectTheme(url: string) {
  const link = document.createElement('link')
  link.rel = 'stylesheet'
  link.href = url
  document.head.appendChild(link)

  const ejectTheme = () => {
    try {
      document.head.removeChild(link)
    } catch (e) {
      console.error(e)
    }
  }

  return ejectTheme
}

export function mergeSettingsWithSchema(
  settings: Record<string, any>,
  schema: Array<SettingSchemaDesc>
) {
  const defaults = (schema || []).reduce((a, b) => {
    if ('default' in b) {
      a[b.key] = b.default
    }
    return a
  }, {})

  // shadow copy
  return Object.assign(defaults, settings)

This function is important because it defines how Logseq: Deep Dive Tutorial implements the patterns covered in this chapter.

How These Components Connect

flowchart TD
    A[cleanInjectedUI]
    B[cleanInjectedScripts]
    C[transformableEvent]
    D[injectTheme]
    E[mergeSettingsWithSchema]
    A --> B
    B --> C
    C --> D
    D --> E
Loading