Rename optimizeEdits to editorMode in MarkdownProcessor

markdown/core/src/main/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessor.kt

@@ -35,15 +35,21 @@ import org.commonmark.node.ListBlock as CMListBlock
  *
  * @param extensions Extensions to use when processing the Markdown (e.g.,
  *    to support parsing custom block-level Markdown).
- * @param optimizeEdits Indicates whether the processing should only update
- *    the changed blocks by keeping a previous state in memory. Default is
- *    `false`; set this to `true` if this parser will be used in an editor
- *    scenario, where the raw Markdown is only ever going to change
- *    slightly but frequently (e.g., as the user types). Setting this to
- *    `true` has a memory cost, and can be a performance regression if the
- *    parse input is not always small variations of the same basic text.
- *    When this is `true`, the instance of [MarkdownProcessor] is **not**
- *    thread-safe!
+ * @param editorMode Indicates whether the processor should be optimized
+ *    for an editor/preview scenario, where it assumes small incremental
+ *    changes as performed by a user typing. This means it will only update
+ *    the changed blocks by keeping state in memory.
+ *
+ *    Default is `false`; set this to `true` if this parser will be used in
+ *    an editor scenario, where the raw Markdown is only ever going to
+ *    change slightly but frequently (e.g., as the user types).
+ *
+ *    **Attention:** do **not** reuse or share an instance of
+ *    [MarkdownProcessor] that is in [editorMode]. Processing entirely
+ *    different Markdown strings will defeat the purpose of the
+ *    optimization. When in editor mode, the instance of
+ *    [MarkdownProcessor] is **not** thread-safe!
+ *
  * @param commonMarkParser The CommonMark [Parser] used to parse the
  *    Markdown. By default it's a vanilla instance provided by the
  *    [MarkdownParserFactory], but you can provide your own if you need to
@@ -54,8 +60,8 @@ import org.commonmark.node.ListBlock as CMListBlock
 @ExperimentalJewelApi
 public class MarkdownProcessor(
     private val extensions: List<MarkdownProcessorExtension> = emptyList(),
-    private val optimizeEdits: Boolean = false,
-    private val commonMarkParser: Parser = MarkdownParserFactory.create(optimizeEdits, extensions),
+    private val editorMode: Boolean = false,
+    private val commonMarkParser: Parser = MarkdownParserFactory.create(editorMode, extensions),
 ) {
     private var currentState = State(emptyList(), emptyList(), emptyList())
 
@@ -76,7 +82,7 @@ public class MarkdownProcessor(
         @Language("Markdown") rawMarkdown: String,
     ): List<MarkdownBlock> {
         val blocks =
-            if (optimizeEdits) {
+            if (editorMode) {
                 processWithQuickEdits(rawMarkdown)
             } else {
                 parseRawMarkdown(rawMarkdown)

markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessorOptimizeEditsTest.kt

@@ -45,7 +45,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `first blocks stay the same`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun =
             processor.processWithQuickEdits(
@@ -80,7 +80,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `first block edited`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun =
             processor.processWithQuickEdits(
@@ -136,7 +136,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `last block edited`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun =
             processor.processWithQuickEdits(
@@ -195,7 +195,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `middle block edited`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun =
             processor.processWithQuickEdits(
@@ -256,7 +256,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `blocks merged`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun =
             processor.processWithQuickEdits(
@@ -313,7 +313,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `blocks split`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun =
             processor.processWithQuickEdits(
@@ -371,7 +371,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `blocks deleted`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun =
             processor.processWithQuickEdits(
@@ -423,7 +423,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `blocks added`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondDocument =
             """
@@ -491,7 +491,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `no changes`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun = processor.processWithQuickEdits(rawMarkdown)
         assertHtmlEquals(
@@ -523,7 +523,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `empty line added`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         val firstRun = processor.processWithQuickEdits(rawMarkdown)
         val secondRun = processor.processWithQuickEdits("\n" + rawMarkdown)
         assertHtmlEquals(
@@ -557,7 +557,7 @@ class MarkdownProcessorOptimizeEditsTest {
     /** Regression https://github.com/JetBrains/jewel/issues/344 */
     @Test
     fun `content if empty`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         processor.processWithQuickEdits(rawMarkdown)
         val secondRun = processor.processWithQuickEdits("")
         assertHtmlEquals(
@@ -570,7 +570,7 @@ class MarkdownProcessorOptimizeEditsTest {
 
     @Test
     fun `chained changes`() {
-        val processor = MarkdownProcessor(optimizeEdits = true)
+        val processor = MarkdownProcessor(editorMode = true)
         processor.processWithQuickEdits(
             """
             # Header 0

samples/standalone/src/main/kotlin/org/jetbrains/jewel/samples/standalone/view/markdown/MarkdownPreview.kt

@@ -56,7 +56,7 @@ internal fun MarkdownPreview(
     // We are doing this here for the sake of simplicity.
     // In a real-world scenario you would be doing this outside your Composables,
     // potentially involving ViewModels, dependency injection, etc.
-    val processor = remember { MarkdownProcessor(extensions, optimizeEdits = true) }
+    val processor = remember { MarkdownProcessor(extensions, editorMode = true) }
 
     LaunchedEffect(rawMarkdown) {
         // TODO you may want to debounce or drop on backpressure, in real usages. You should also not do this