V0.3.0/release by thanos · Pull Request #143 · thanos/ex_editor

thanos · 2026-04-09T18:20:49Z

ExEditor v0.3.0 Implementation Summary

Final Implementation (April 9, 2026)

This document summarizes the complete v0.3.0 implementation of ExEditor, including the initial LiveView component work and subsequent optimization to incremental diff synchronization.

Major Fixes

0. Incremental Diff Synchronization (Latest Optimization)

Problem: Typing mode UX (plain text visible, highlight delayed 2 seconds) felt jarring
Solution: Send incremental diffs instead of full content on fast debounce
Implementation:

Editor.apply_diff/4 function for {from, to, text} operations
JavaScript computeDiff() algorithm using longest common prefix/suffix
Event change: "change" (full content) for blur/paste, "diff" (incremental) for typing
Default debounce: 300ms → 50ms (now debounces diffs, not highlight fades)

1. Cursor Alignment Bug (Lines 7+)

Problem: Cursor position diverged from visible text starting at line 7, with growing offset
Root Cause: Newline characters between <div class="ex-editor-line"> elements in the highlight layer were rendered as visible blank lines (due to white-space: pre), roughly doubling the visual height vs. textarea
Solution: Changed Enum.map_join("", ...) in HighlightedLines module (removed newline separator)

2. Fake Cursor Disappearance

Problem: When user typed, cursor would disappear on the next server update
Root Cause: Fake cursor was a DOM element appended to <pre>, which LiveView would patch/replace, destroying the appended element
Solution: Replaced fake cursor overlay with native browser caret (caret-color: #d4d4d4)
Benefit: Cursor now always works because it's native behavior, not JavaScript manipulation

3. Line Numbers Lag

Problem: Adding/deleting lines showed stale line numbers until server round-trip completed (300-500ms)
Root Cause: Line numbers were only updated by server, waiting for debounce + network latency
Solution: Moved line number updates to JavaScript hook (updateLineNumbers())
Result: Instant line count updates on every keystroke

4. Heredoc String Line Count

Problem: After heredoc blocks, all subsequent lines in highlight layer were 1 line short
Root Cause: Elixir highlighter's extract_heredoc consumed closing delimiter but didn't add it back to token
Solution: Changed heredoc token to include trailing newline in output

5. Multi-line String Spans

Problem: Spans containing newlines would break HTML structure when HighlightedLines split on newlines
Root Cause: Strings with embedded newlines wrapped entire value in one <span>, leaving spans unclosed across <div> boundaries
Solution: Split string value on newlines and wrap each line in its own <span>

Architectural Approach: Incremental Diffs

Content Synchronization Strategy

User types → Compute diff:
  - Compare previous content with current textarea value
  - Send only {from, to, text} operation (~20 bytes)
  - Default 50ms debounce batches rapid keystrokes

Server processes diff:
  - Apply diff to reconstruct full content
  - Run syntax highlighter
  - Send back updated highlighting HTML

Rendering:
  - Highlight layer always visible (opacity: 1)
  - Lags by ~50ms (debounce) + network latency (~50-100ms)
  - Total latency: ~100-150ms vs 2000ms+ typing mode

Benefits:

Smaller payloads (4-6x reduction)
Faster server processing
Always-visible syntax highlighting
No jarring gap between plain text and highlighting

Layout Fixes

Fixed CSS class mismatch: .ex-editor-gutter now has proper styling
Fixed flex layout with .ex-editor-wrapper, .ex-editor-gutter, .ex-editor-code-area
Made gutter scrollable with hidden scrollbar: overflow-y: scroll; scrollbar-width: none;
Added phx-update="ignore" to gutter and textarea to prevent LiveView from patching them

Testing Additions

Tests Created

test/ex_editor_test.exs - 8 tests for public API
test/ex_editor/editor_test.exs - 11 new tests for apply_diff/4 edge cases
test/ex_editor/highlighter_test.exs - 18 tests for syntax highlighting
test/ex_editor/plugin_test.exs - 12 tests for plugin system
test/ex_editor_web_test.exs - 1 test for web module existence
test/ex_editor_web/live_editor_test.exs - 8 tests for component module
test/ex_editor_web/live_editor_logic_test.exs - 14 tests for rendering pipeline
test/ex_editor_web/live_editor_component_test.exs - 20 tests with phoenix_test
test/ex_editor_web/live_editor_event_test.exs - 6 new tests for diff event processing (plus original 13)

Coverage Results

Metric	Before	After	Status
Total tests	267	285	✅
Doctests	12	12	✅
Unit tests	255	273	✅
Overall coverage	79.4%	88.7%	✅

Code Changes

Core Modules

lib/ex_editor/editor.ex - Added apply_diff/4 function with doctests
lib/ex_editor/highlighted_lines.ex - Removed newlines between divs
lib/ex_editor/highlighters/elixir.ex - Fixed heredoc line count, split multi-line strings
demo/assets/js/hooks/editor.js - Rewritten for incremental diffs, added computeDiff() algorithm (~130 lines)
lib/ex_editor_web/css/editor.css - Removed typing mode styles, kept highlight always visible
lib/ex_editor_web/live_editor.ex - Added handle_event("diff") for incremental sync, changed debounce default 300→50

Demo Application

Removed explicit debounce attribute (uses new 50ms default)
Removed typing mode transition visuals
Restructured layout: editor and raw preview side by side with aligned headings

Configuration

Added phoenix_test (~> 0.2) dependency for LiveComponent testing

Commits

Initial v0.3.0: LiveView Component & Bug Fixes
- Add LiveEditor component with double-buffer rendering
- Remove newlines from highlighted line wrapping
- Fix Elixir highlighter heredoc line count
- Fix multi-line string span formatting
- Replace fake cursor with native caret
- Add JS-managed line numbers
Incremental Diff Optimization
- Implement Editor.apply_diff/4 for text operations
- Add computeDiff() algorithm in JS hook
- Send incremental diffs on 50ms debounce
- Remove typing mode (plain text + fade-in UX)
- Add safety full-sync on blur/paste
- Reduce payloads 4-6x
Comprehensive Test Suite
- Add 285 total tests (12 doctests + 273 unit tests)
- Add 11 tests for apply_diff/4
- Add 6 tests for diff event processing
- Add LiveComponent tests with phoenix_test
- Achieve 88.7% coverage
Documentation & Demo
- Update CHANGELOG, README, RELEASE_NOTES
- Enhance Highlighter and Plugin behavior documentation with examples
- Restructure demo: side-by-side editor and preview
- Fix credo issues in demo app

Performance Impact

Metric	Impact	Benefit
Payload per keystroke	~20 bytes vs ~120 bytes	4-6x reduction
Highlighting latency	~50-150ms vs 2000+ms	12x faster
Line number latency	0ms (JS) vs 300+ms	Instant
Server processing	Smaller deltas	Faster CPU/memory
Network efficiency	Only changes sent	Reduced bandwidth

Backward Compatibility

No breaking changes. All public APIs remain the same. The improvements are transparent to users of the library.

Known Limitations

Monospace font required for cursor alignment
Max ~10k lines recommended (virtualization future feature)
Mobile touch behavior not fully tested (future improvement)

Implementation Stats

Code Changes

Lines of code changed: ~500+ (including incremental diff implementation)
Core modules updated: 6 (editor.ex, highlighted_lines.ex, elixir.ex, editor.js, editor.css, live_editor.ex)
New functions: Editor.apply_diff/4, computeDiff() in JavaScript

Testing

Tests added: 18 new tests (11 for apply_diff + 6 for diff events + 1 for debounce default)
Total test suite: 285 tests (12 doctests + 273 unit tests)
Coverage: 88.7% overall, up from 79.4%

Performance

Payload reduction: 4-6x smaller (avg ~20 bytes vs ~120 bytes)
Highlighting latency: 12x faster (~50-150ms vs 2000+ms)
Line number latency: Instant (0ms via JavaScript)

Bugs Fixed

Cursor alignment divergence (2-line offset from line 7+)
Cursor disappearance on type
Line numbers lagging behind typing
Highlighting gap during content sync
Heredoc string line count offset
Multi-line string span HTML malformation

Timeline

Session 1: LiveView component, double-buffer rendering, bug fixes (4 hours)
Session 2: Incremental diff optimization, testing, documentation (3 hours)
Total: ~7 hours from v0.2.0 to production-ready v0.3.0

…105 - Add ExEditor.LineNumbers module for rendering line numbers HTML - closed #106 - Add ExEditor.HighlightedLines for wrapping highlighted content line-by-line - closed #107 - Create lib/ex_editor_web directory structure for LiveView components - closed #108 - Update mix.exs with package files and module documentation groups - Add convenience functions ExEditor.new/1 and ExEditor.document_from_text/1 - Bump version to 0.3.0-dev Issues Closed

…losed #109 - Create ExEditorWeb.LiveEditor LiveComponent for embedding in Phoenix LiveView - closed #110 - Implement HEEx template with double-buffer rendering (invisible textarea + visible highlighted layer) - closed #111 - Add line numbers gutter support with VS Code-inspired styling - Support content and editor struct props with automatic highlighter setup - Add debounced content change events with configurable event names = closed #112 - Add phoenix_live_view and phoenix_html as optional dependencies - Create integration guide with usage examples and troubleshooting - Fix credo issues: use Enum.map_join/3, alias ordering, nested module aliases

#113 Phase 3 of v0.3.0 implementation: - Create editor.js hook with mounted/destroyed lifecycle - closed #114 - Implement scroll synchronization between textarea and highlighted layers - Add cursor position calculation from selectionStart - closed #115 - Render fake cursor with blink animation (530ms interval) - Handle focus/blur events for cursor visibility - Create default CSS styles for double-buffer layout - Update demo to use LiveEditor component with new hook - Rewrite demo tests for new component architecture - closed #116

…ll sync - Remove fake cursor (JS-appended element was destroyed on every LiveView DOM patch) - closed #117 - Use native browser caret: caret-color: #d4d4d4 on textarea instead of transparent - closed #118 - Add JS-managed line numbers: count lines from textarea on every input event, update gutter immediately without waiting for server round-trip - closed #119 - Add phx-update="ignore" to gutter so LiveView never overwrites JS-managed counts - closed #120 - Add updated() hook callback to re-sync scroll position after server patches highlight layer - closed #121 - Fix gutter scroll sync: change overflow: hidden to overflow-y: scroll with hidden scrollbar so scrollTop can be mirrored from textarea - closed #122 - Fix CSS layout: rewrite editor.css with correct flex structure (ex-editor-wrapper, ex-editor-gutter, ex-editor-code-area) replacing broken absolute positioning - closed #123 - Remove ex-editor-cursor styles from both CSS files (no longer used) - closed #124 - JS hook reduced from 168 to 95 lines - closed #125

Three bugs caused cursor position to diverge from visible text: 1. HighlightedLines.wrap_lines/wrap_lines_with_empties joined <div> elements with "\n" separators. Inside a <pre> with white-space: pre, those text nodes rendered as visible blank lines, roughly doubling the visual height of the highlight layer vs. the textarea. Fixed by joining with "". 2. The Elixir highlighter's extract_heredoc consumed the closing """\n but never added the \n back to the token value. Every heredoc caused all subsequent lines in the highlight to be 1 line short of the textarea. Fixed by appending \n to the heredoc string token: ~s("""\n#{string}"""\n). 3. format_token for strings wrapped the full multi-line value in a single <span>, leaving spans unclosed across <div> line boundaries (malformed HTML). Fixed by splitting on \n and wrapping each line in its own span.

- closed #129 - Reduce debounce to 50-100ms - closed #130 - can the fade in happen after 2 seconds of inactivity and be a bit slower?

…d best practices - Add detailed event system explanation (:before_change vs :handle_change semantics) - Add 4 complete examples: MaxLength, ChangeTracker, JSONFormatter, SyntaxChecker - Document plugin composition and error handling patterns - Add best practices section covering separation of concerns, defensive error handling, performance, idempotency, testing - Add LiveView integration guide - Provide comprehensive guidance for plugin developers

PLT (Persistent Lookup Table) files should not be committed as they become stale and incompatible across different OTP/Elixir versions and CI environments. They are already in .gitignore and will be regenerated on first run. Fixes CI Dialyzer error: 'Old PLT file'

…it tracking

…ode) Replaces the problematic "typing mode" UX with incremental diffs sent on a fast debounce (50ms). This keeps the syntax-highlighted layer always visible, reducing UX gap from 2 seconds to ~50ms. Core changes: - Add Editor.apply_diff/4 to apply text operations (insert/delete/replace) - JS hook: remove showTypingMode/showHighlightMode, add computeDiff - JS hook: send "diff" events with {from, to, text} instead of full content - JS hook: add blur/paste safety sync to prevent divergence - LiveEditor: add handle_event("diff") to apply diffs and re-render - CSS: remove .typing mode styles and opacity transitions - Default debounce: 300ms → 50ms (now debounces diffs, not highlights) - Demo: remove explicit debounce={2000}, use new 50ms default Tests: - Add 11 tests for Editor.apply_diff edge cases - Add 6 tests for diff event processing - Update debounce default assertion: 300 → 50 - All 285 tests pass (was 267) Benefits: - No jarring "unhighlighted" gap during typing - Smaller payloads (avg ~20 bytes vs full content) - Faster server processing per event - Syntax highlighting stays visible and just lags ~50ms - Natural UX pattern: previous highlights stay while new ones load

- Add alias Phoenix.HTML.Form in CoreComponents - Add aliases Demo.CMS.CodeSnippet and DemoWeb.Layouts in CodeSnippetLive - Fix alphabetical ordering of aliases in demo_web.ex (DemoWeb.Layouts before Phoenix.LiveView.JS) - Remove parentheses from skip_migrations?/0 function definition All credo checks now pass (76 mods/funs, found no issues)

- Use CSS Grid (grid-cols-2) for two equal columns - Editor on left, raw content preview on right - Both panels height 600px with independent scrolling - Preview updates reactively as user edits code

- Add 'Editor' heading to match 'Raw Content (Preview)' heading - Both headings now aligned at the top - Use flexbox to ensure equal spacing and alignment

Update CHANGELOG.md: - Reflect incremental diff approach instead of typing mode - Add performance metrics (4-6x smaller payloads, 12x faster highlighting) - Document apply_diff/4 function and diff event handling - Update debounce strategy and test counts (285 tests) Update README.md: - Replace 'typing mode' with 'responsive highlighting' - Highlight incremental diffs and payload reduction - Update feature list and test count Update RELEASE_NOTES-0.3.0.md: - Complete rewrite focusing on incremental diffs - Add performance comparison table - Emphasize always-visible syntax highlighting vs typing mode gap - Document payload reduction and latency improvements Update VERSION-0.3.0-SUMMARY.md: - Add incremental diff synchronization as major improvement - Describe diff computation strategy and benefits - Update test counts and coverage metrics - Document all code changes across modules - Add performance impact table - Update implementation stats with final numbers

Integrate the ExEditor LiveEditor component into the Backpex admin interface for code snippet editing. Changes: - Update EditField to use ExEditor.LiveEditor component instead of textarea - Display with syntax-highlighted editing in admin forms - Configure with Elixir language highlighting - Set 100-line height (h-96) for better editing experience - Support readonly mode - Add EditorFormSync hook to sync editor changes with form input - Listen for code_changed events - Update hidden form input with editor content - Trigger change event for form validation - Update CodeSnippetLive to handle code_changed events - Add handle_info for tracking editor state changes Benefits: - Admin users get full-featured syntax-highlighted code editor - Same experience as main demo editor - Seamless integration with Backpex form system - Editor content properly synced with form submission

Extract field values properly from Backpex form/item assigns: - In render_form: get value from form field (form[name].value) - In render_value: get value from item (item[name]) Fixes KeyError when rendering the edit field for code snippets.

The EditorFormSync hook now syncs the textarea value directly to the hidden form input instead of waiting for LiveView events. This ensures the form always has the current editor content when submitted. Changes: - Listen to textarea 'input' and 'blur' events - Find textarea via EditorHook container - Sync immediately on mount and continuously during editing - Ensures form submission captures all code changes Testing: - Verified typing updates hidden input in real-time - Confirmed form submission saves code to database - Validated content persistence across page reloads

Display syntax-highlighted code with line numbers when viewing a code snippet on the show page. This provides better code readability and makes it easier to reference specific lines. Changes: - Updated render_value/1 to detect show action - Added render_code_with_lines/1 for show view formatting - Added line_count/1 helper to count lines in content - Styled gutter with dark theme matching editor - Index and resource action views remain truncated

Added documentation for using ExEditor with Backpex admin panels: Updates: - Updated README.md with Backpex integration section * Setup instructions with custom field implementation * Complete example code for field rendering * Form sync hook configuration * Feature highlights - Updated CHANGELOG.md to mention Backpex integration * Custom field implementation * Readonly display with line numbers * Form sync hook * Example in demo application - Created guides/BACKPEX_INTEGRATION.md with: * Installation and setup * Step-by-step field implementation * Configuration options * Customization guide * Integration patterns * Troubleshooting section * Performance tips * Complete working example reference

Added comprehensive Backpex integration information to release notes: - New section: 'Backpex Admin Panel Integration' * Features overview (edit/view modes, form integration, line numbers) * Example of field configuration * Demo application instructions * Link to detailed integration guide - Updated 'What's New in v0.3.0' * Highlighted Backpex admin panel integration * Updated demo application features * Added reference to integration guide This provides users with immediate visibility into the Backpex integration capabilities and points them to comprehensive documentation.

Created two release announcements tailored for different communities: 1. REDDIT_ANNOUNCEMENT.md - For r/elixir subreddit - Concise, bullet-point focused format - Emphasizes performance metrics (4-6x smaller payloads) - Highlights key features and differentiators - Includes links to live demo and documentation - Professional but accessible tone 2. ELIXIR_FORUM_ANNOUNCEMENT.md - For Elixir Forum - Discussion-oriented, conversational tone - Detailed explanations of improvements - Architecture explanation with ASCII diagram - Quick start guide with code examples - Encourages community feedback - Complete links section Both include prominent links to: - Live demo: https://ex-editor.fly.dev - Hex package and documentation - GitHub repository - Backpex integration guide

The Backpex.Field.translate_errors/2 function doesn't exist in the current version of Backpex. Fixed by using translate_error_fun/2 directly to map over error tuples. Changed from: Backpex.Field.translate_errors(errors, fun) To: errors |> Enum.map(&(fun.(&1))) This resolves the compilation warning while maintaining proper error translation with the field's custom error function.

thanos added 30 commits April 2, 2026 19:59

version set to 0.2.0

2d492fc

update CHANGELOG

d08b7f8

cleaned up the git tracing, closed #104

5d344b6

added fix to backpex demo

168a8db

bump small fixes

fafc864

- closed #128 - Show plain text while typing

f38b551

- closed #129 - Reduce debounce to 50-100ms - closed #130 - can the fade in happen after 2 seconds of inactivity and be a bit slower?

fix: escape string interpolation in Plugin docstring example

24bcbc2

updated for release v0.3.0

2cd99fa

added credo excemptions

9bab6ca

Removed priv/plts/dialyzer.plt and priv/plts/dialyzer.plt.hash from g…

4907fe3

…it tracking

fixes to format and credo issues

814bc20

demo: display editor and raw content preview side by side

2ac7c7a

- Use CSS Grid (grid-cols-2) for two equal columns - Editor on left, raw content preview on right - Both panels height 600px with independent scrolling - Preview updates reactively as user edits code

demo: add heading to editor section for alignment

ba24836

- Add 'Editor' heading to match 'Raw Content (Preview)' heading - Both headings now aligned at the top - Use flexbox to ensure equal spacing and alignment

added more tests on the demo app

7a1fe2e

ready for release

5c0774a

thanos added 7 commits April 9, 2026 13:32

local cleanup before release

545ce4f

local cleanup before release

d2e422c

local cleanup before release

63efd22

local cleanup before release

cc2dd09

thanos merged commit 6e523a6 into main Apr 9, 2026
17 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

V0.3.0/release#143

V0.3.0/release#143
thanos merged 37 commits into
mainfrom
v0.3.0/release

thanos commented Apr 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

thanos commented Apr 9, 2026

ExEditor v0.3.0 Implementation Summary

Final Implementation (April 9, 2026)

Major Fixes

0. Incremental Diff Synchronization (Latest Optimization)

1. Cursor Alignment Bug (Lines 7+)

2. Fake Cursor Disappearance

3. Line Numbers Lag

4. Heredoc String Line Count

5. Multi-line String Spans

Architectural Approach: Incremental Diffs

Content Synchronization Strategy

Layout Fixes

Testing Additions

Tests Created

Coverage Results

Code Changes

Core Modules

Demo Application

Configuration

Commits

Performance Impact

Backward Compatibility

Known Limitations

Implementation Stats

Code Changes

Testing

Performance

Bugs Fixed

Timeline

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant