feat: monaco editor folding range provider (#11)

Author: adamdehaven

README.md

@@ -19,7 +19,7 @@ npm install @nuxtlabs/monarch-mdc
 
 ## Usage
 
-The package provides both the MDC language syntax for the Monaco Editor, along with an optional formatter function.
+The package provides both the MDC language syntax for the Monaco Editor, along with optional formatting and code folding providers.
 
 Checkout the [Editor.vue](./playground/components/Editor.vue) for a complete example.
 
@@ -82,7 +82,7 @@ monaco.languages.registerDocumentFormattingEditProvider('mdc', {
       tabSize: TAB_SIZE,
     }),
   }],
-});
+})
 
 // Register format on type provider
 monaco.languages.registerOnTypeFormattingEditProvider('mdc', {
@@ -96,7 +96,7 @@ monaco.languages.registerOnTypeFormattingEditProvider('mdc', {
       isFormatOnType: true,
     }),
   }],
-});
+})
 
 const code = `
 Your **awesome** markdown
@@ -121,6 +121,43 @@ const editor = monaco.editor.create(el, {
 })
 ```
 
+### Code Folding
+
+If you'd like to enable code folding for MDC block components into your Monaco Editor instance, you can also register the folding range provider.
+
+```js
+import * as monaco from 'monaco-editor'
+import { language as markdownLanguage, foldingProvider as markdownFoldingProvider } from '@nuxtlabs/monarch-mdc'
+
+// Register language
+monaco.languages.register({ id: 'mdc' })
+monaco.languages.setMonarchTokensProvider('mdc', markdownLanguage)
+
+// Register code folding provider
+monaco.languages.registerFoldingRangeProvider('mdc', {
+  provideFoldingRanges: model => markdownFoldingProvider(model),
+})
+
+const code = `
+Your **awesome** markdown
+`
+
+// Create monaco model
+const model = monaco.editor.createModel(
+  code,
+  'mdc'
+)
+
+// Create your editor
+const el = ... // DOM element
+const editor = monaco.editor.create(el, {
+  model,
+  folding: true, // Enable code folding for MDC block components
+  // Other Monaco Editor options
+  // see: https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.istandaloneeditorconstructionoptions.html
+})
+```
+
 ## 💻 Development
 
 - Clone repository

playground/components/Editor.vue

@@ -8,7 +8,11 @@
 <script setup>
 import { ref, onMounted, watch } from 'vue'
 import loader from '@monaco-editor/loader'
-import { language as mdc, formatter as mdcFormatter } from '../../src/index'
+import {
+  language as mdc,
+  formatter as mdcFormatter,
+  foldingProvider as mdcFoldingProvider,
+} from '../../src/index'
 
 const props = defineProps({
   code: {
@@ -48,6 +52,7 @@ onMounted(async () => {
       }),
     }],
   })
+
   // Register format on type provider
   monaco.languages.registerOnTypeFormattingEditProvider('mdc', {
     // Auto-format when the user types a newline character.
@@ -62,6 +67,11 @@ onMounted(async () => {
     }],
   })
 
+  // Register code folding provider
+  monaco.languages.registerFoldingRangeProvider('mdc', {
+    provideFoldingRanges: model => mdcFoldingProvider(model),
+  })
+
   editor = monaco.editor.create(editorContainer.value, {
     value: props.code,
     language: props.language,
@@ -81,6 +91,7 @@ onMounted(async () => {
     bracketPairColorization: {
       enabled: true,
     },
+    folding: true, // Enable code folding for MDC block components
     tabSize: TAB_SIZE, // Utilize the same tabSize used in the format providers
     detectIndentation: false, // Important as to not override tabSize
     insertSpaces: true, // Since the formatter utilizes spaces, we set to true to insert spaces when pressing Tab

src/folding-provider.ts

@@ -0,0 +1,55 @@
+import type { languages, editor } from 'monaco-editor-core'
+
+/**
+ * Provides folding ranges for the MDC language in the Monaco editor.
+ *
+ * @param {monaco.editor.ITextModel} model - The text model to provide folding ranges for.
+ * @returns {languages.ProviderResult<languages.FoldingRange[]>} An array of folding ranges for the editor.
+ *
+ * The function identifies folding ranges based on:
+ * - Custom block components defined by start tags (e.g., "::container" or ":::button")
+ *   and end tags (e.g., "::" or ":::" with matching opening tag level).
+ * - Markdown code blocks delimited by triple backticks (```) or tildes (~~~).
+ */
+export const foldingProvider = (model: editor.ITextModel): languages.ProviderResult<languages.FoldingRange[]> => {
+  const ranges = [] // Array to store folding ranges
+  const stack = [] // Stack to manage nested block components
+  const lines = model.getLinesContent() // Retrieve all lines
+  let insideCodeBlock = false // Flag to track if inside a code block
+
+  for (let lineNumber = 0; lineNumber < lines.length; lineNumber++) {
+    const line = lines[lineNumber].trim() // Remove extra whitespace
+
+    // Check if the current line starts or ends a markdown code block
+    if (/^\s*(?:`{3,}|~{3,})/.test(line)) {
+      insideCodeBlock = !insideCodeBlock // Toggle code block mode
+      continue // Skip further processing for this line
+    }
+
+    // Skip processing lines inside a markdown code block
+    if (insideCodeBlock) {
+      continue
+    }
+
+    // Match the start tag (e.g., "::container" or ":::button")
+    const startMatch = line.match(/^\s*:{2,}([\w-]+)/)
+    if (startMatch) {
+      // Push start block onto the stack
+      stack.push({ start: lineNumber + 1, tagName: startMatch[1] }) // Save 1-based line number and tag name
+      continue // Skip further processing for this line
+    }
+
+    // Match the end tag (e.g., "::" or ":::" with matching opening tag level)
+    const endMatch = line.match(/^\s*:{2,}$/)
+    if (endMatch && stack.length > 0) {
+      const lastBlock = stack.pop() // Retrieve the last unmatched start block
+      ranges.push({
+        start: lastBlock?.start ?? 0, // Block start line (1-based)
+        end: lineNumber + 1, // Current line as block end (1-based)
+      })
+    }
+  }
+
+  // Return all folding ranges to the editor
+  return ranges
+}

src/formatter.ts

@@ -29,6 +29,8 @@ const COMPONENT_START_REGEX = /^\s*:{2,}[\w-]+/
 const COMPONENT_END_REGEX = /^\s*:{2,}\s*$/
 // Matches YAML multiline indicators "|" or ">"
 const MULTILINE_STRING_REGEX = /^[\w-]+:\s*[|>]/
+// Matches markdown code block opening tags like "```" or "~~~"
+const CODE_BLOCK_REGEX = /^\s*(?:`{3,}|~{3,})/
 
 /**
  * Cache for commonly used indentation strings to avoid repeated string creation
@@ -71,9 +73,9 @@ export const formatter = (content: string, { tabSize = 2, isFormatOnType = false
   let insideCodeBlock = false
   // Current position in output array
   let formattedIndex = 0
-  // Base indent for the current markdown code block
+
+  // Add new state variable at top of function
   let codeBlockBaseIndent: number | null = null
-  // The original indent of the markdown code block line
   let codeBlockOriginalIndent: number | null = null
 
   const yamlState: YamlState = {
@@ -101,8 +103,8 @@ export const formatter = (content: string, { tabSize = 2, isFormatOnType = false
       continue
     }
 
-    // Handle code block markers (```)
-    if (trimmedContent.startsWith('```')) {
+    // Handle code block markers (``` or ~~~)
+    if (CODE_BLOCK_REGEX.test(trimmedContent)) {
       insideCodeBlock = !insideCodeBlock
       if (insideCodeBlock) {
         codeBlockBaseIndent = parentIndent

src/index.ts

@@ -253,3 +253,4 @@ export const language = <languages.IMonarchLanguage>{
 }
 
 export { formatter } from './formatter'
+export { foldingProvider } from './folding-provider'