markdown-to-slack-blocks 1.0.0 → 1.1.0

package/README.md

@@ -13,6 +13,14 @@ While Slack does offer native [markdown support in blocks](https://api.slack.com
 
 This library is particularly useful for apps that leverage **platform AI features** where you expect a **markdown response from an LLM**. Instead of sending raw markdown that Slack can't fully render, this library converts it to proper Block Kit JSON that displays correctly.
 
+### Additional Features
+
+Beyond basic markdown conversion, this library provides:
+
+- **Mention Support**: User, channel, user group, and team mentions (`@username`, `#channel`) are automatically detected and converted to Slack's native mention format when ID mappings are provided. Without mappings, mentions are rendered as plain text.
+- **Native Slack Dates**: Support for Slack's date formatting syntax, allowing dynamic date rendering that respects user timezones.
+- **Color Detection**: Optional color detection that converts color values (hex, rgb, named colors) into Slack's native color elements for rich visual formatting.
+
 ## How It Works
 
 This library uses a two-step conversion process:
@@ -129,3 +137,25 @@ The library validates that the IDs provided in the `mentions` option adhere to S
 - **Team IDs**: Must start with `T`.
 
 All IDs must be alphanumeric.
+
+### Handling Large Messages
+
+Slack limits messages to **~45 blocks** and **~12KB** of JSON. Use `splitBlocks` to split large outputs:
+
+```typescript
+import { markdownToBlocks, splitBlocks } from 'markdown-to-slack-blocks';
+
+const blocks = markdownToBlocks(veryLongMarkdown);
+const batches = splitBlocks(blocks);
+
+for (const batch of batches) {
+    await slack.postMessage({ channel, blocks: batch });
+}
+```
+
+**Options:**
+```typescript
+splitBlocks(blocks, { maxBlocks: 40, maxCharacters: 12000 });
+```
+
+The function splits at natural boundaries: between blocks first, then within `rich_text` elements, and finally within large code blocks by line.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { MarkdownToBlocksOptions } from './types';
 export * from './types';
+export { splitBlocks, SplitBlocksOptions } from './splitter';
 export declare function markdownToBlocks(markdown: string, options?: MarkdownToBlocksOptions): import("./types").Block[];
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAIlD,cAAc,SAAS,CAAC;AAExB,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,6BAGnF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAIlD,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE7D,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,6BAGnF"}

package/dist/index.js

@@ -14,11 +14,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitBlocks = void 0;
 exports.markdownToBlocks = markdownToBlocks;
 const parser_1 = require("./parser");
 const validator_1 = require("./validator");
 // Re-export types for consumers
 __exportStar(require("./types"), exports);
+var splitter_1 = require("./splitter");
+Object.defineProperty(exports, "splitBlocks", { enumerable: true, get: function () { return splitter_1.splitBlocks; } });
 function markdownToBlocks(markdown, options) {
     (0, validator_1.validateOptions)(options);
     return (0, parser_1.parseMarkdown)(markdown, options);

package/dist/parser.js

@@ -176,7 +176,6 @@ function parseMarkdown(markdown, options = {}) {
     return blocks;
 }
 function mapInlineNode(node, options) {
-    // console.log('Node:', node.type, node.value || node);
     if (node.type === 'text' || node.type === 'html') {
         // Pass empty object for style, processTextNode will handle it (and not attach if empty)
         return processTextNode(node.value, {}, options);
@@ -219,10 +218,6 @@ function flattenStyles(children, style, options) {
             return { ...el, style: mergedStyle };
         }
         // If it was empty before and we're not adding anything (shouldn't happen here if style has keys), just return
-        // But if el.style was undefined and style is {}, we want undefined.
-        // Logic: if mergedStyle has keys, use it. Else, if el had style, keep it? No, we want to flatten.
-        // Actually, if we merge {bold: true} with {}, we get {bold: true}.
-        // If we merge {} with {}, we get {}. We want to avoid {}.
         const { style: _, ...rest } = el;
         return rest;
     });
@@ -238,8 +233,6 @@ function processTextNode(text, style, options) {
     // 7. Emoji: :shortcode:
     // 8. Mapped Mention: @name
     // 9. Mapped Channel: #name
-    // Note: JS Regex stateful global matching
-    // We need to capture everything carefully.
     // Groups:
     // 1. Broadcast: (<!here>|<!channel>|<!everyone>)
     // 2. Mention: (<@([\w.-]+)>)

package/dist/splitter.d.ts

@@ -0,0 +1,17 @@
+import { Block } from './types';
+export interface SplitBlocksOptions {
+    /** Maximum number of blocks per message. Default: 40 */
+    maxBlocks?: number;
+    /** Maximum JSON character count per message. Default: 12000 */
+    maxCharacters?: number;
+}
+/**
+ * Splits an array of blocks into multiple arrays that fit within Slack's limits.
+ * Attempts to split at natural boundaries (between top-level blocks, rich_text elements, etc.)
+ *
+ * @param blocks - Array of blocks from markdownToBlocks
+ * @param options - Optional configuration for limits
+ * @returns Array of block arrays, each fitting within the limits
+ */
+export declare function splitBlocks(blocks: Block[], options?: SplitBlocksOptions): Block[][];
+//# sourceMappingURL=splitter.d.ts.map

package/dist/splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitter.d.ts","sourceRoot":"","sources":["../src/splitter.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,EAIR,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,kBAAkB;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAKD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,EAAE,EAAE,CAkEpF"}

package/dist/splitter.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitBlocks = splitBlocks;
+const DEFAULT_MAX_BLOCKS = 40;
+const DEFAULT_MAX_CHARACTERS = 12000;
+/**
+ * Splits an array of blocks into multiple arrays that fit within Slack's limits.
+ * Attempts to split at natural boundaries (between top-level blocks, rich_text elements, etc.)
+ *
+ * @param blocks - Array of blocks from markdownToBlocks
+ * @param options - Optional configuration for limits
+ * @returns Array of block arrays, each fitting within the limits
+ */
+function splitBlocks(blocks, options) {
+    const maxBlocks = options?.maxBlocks ?? DEFAULT_MAX_BLOCKS;
+    const maxChars = options?.maxCharacters ?? DEFAULT_MAX_CHARACTERS;
+    if (blocks.length === 0) {
+        return [[]];
+    }
+    // Check if everything fits in one message
+    if (blocks.length <= maxBlocks && JSON.stringify(blocks).length <= maxChars) {
+        return [blocks];
+    }
+    const result = [];
+    let currentBatch = [];
+    const fitsInBatch = (batch, newBlock) => {
+        if (batch.length + 1 > maxBlocks)
+            return false;
+        const newSize = JSON.stringify([...batch, newBlock]).length;
+        return newSize <= maxChars;
+    };
+    const flushBatch = () => {
+        if (currentBatch.length > 0) {
+            result.push(currentBatch);
+            currentBatch = [];
+        }
+    };
+    for (const block of blocks) {
+        // Try to add block to current batch
+        if (fitsInBatch(currentBatch, block)) {
+            currentBatch.push(block);
+            continue;
+        }
+        // Block doesn't fit - flush current batch first
+        flushBatch();
+        // Check if this single block fits on its own
+        if (fitsInBatch([], block)) {
+            currentBatch.push(block);
+            continue;
+        }
+        // Single block is too large - try to split it
+        if (block.type === 'rich_text') {
+            const splitRichText = splitLargeRichTextBlock(block, maxBlocks, maxChars);
+            for (const subBlock of splitRichText) {
+                if (fitsInBatch(currentBatch, subBlock)) {
+                    currentBatch.push(subBlock);
+                }
+                else {
+                    flushBatch();
+                    currentBatch.push(subBlock);
+                }
+            }
+        }
+        else {
+            // For non-rich_text blocks that are too large, we have to include them as-is
+            // (tables, images, etc. can't really be split semantically)
+            currentBatch.push(block);
+        }
+    }
+    flushBatch();
+    return result.length > 0 ? result : [[]];
+}
+/**
+ * Splits a large RichTextBlock into smaller RichTextBlocks by splitting its elements
+ */
+function splitLargeRichTextBlock(block, maxBlocks, maxChars) {
+    const elements = block.elements;
+    if (elements.length === 0) {
+        return [block];
+    }
+    // First, try splitting by elements
+    const elementBlocks = splitRichTextByElements(elements, maxChars);
+    // If any single element is still too large, try to split it further
+    const result = [];
+    for (const elementBlock of elementBlocks) {
+        const blockJson = JSON.stringify(elementBlock);
+        if (blockJson.length <= maxChars) {
+            result.push(elementBlock);
+        }
+        else {
+            // Try to split individual elements (e.g., large code blocks)
+            const furtherSplit = splitRichTextBlockElements(elementBlock, maxChars);
+            result.push(...furtherSplit);
+        }
+    }
+    return result;
+}
+/**
+ * Splits rich_text elements into separate RichTextBlocks
+ */
+function splitRichTextByElements(elements, maxChars) {
+    const result = [];
+    let currentElements = [];
+    const createBlock = (elems) => ({
+        type: 'rich_text',
+        elements: elems,
+    });
+    for (const element of elements) {
+        const testBlock = createBlock([...currentElements, element]);
+        const testJson = JSON.stringify(testBlock);
+        if (testJson.length <= maxChars) {
+            currentElements.push(element);
+        }
+        else {
+            // Flush current elements
+            if (currentElements.length > 0) {
+                result.push(createBlock(currentElements));
+                currentElements = [];
+            }
+            // Add this element to a new batch
+            currentElements.push(element);
+        }
+    }
+    if (currentElements.length > 0) {
+        result.push(createBlock(currentElements));
+    }
+    return result.length > 0 ? result : [createBlock([])];
+}
+/**
+ * Attempts to split individual elements within a RichTextBlock (e.g., large code blocks)
+ */
+function splitRichTextBlockElements(block, maxChars) {
+    const result = [];
+    for (const element of block.elements) {
+        if (element.type === 'rich_text_preformatted') {
+            // Split large code blocks by lines
+            const splitPreformatted = splitPreformattedElement(element, maxChars);
+            for (const splitElem of splitPreformatted) {
+                result.push({
+                    type: 'rich_text',
+                    elements: [splitElem],
+                });
+            }
+        }
+        else {
+            // For other element types, just wrap them as-is
+            result.push({
+                type: 'rich_text',
+                elements: [element],
+            });
+        }
+    }
+    return result.length > 0 ? result : [block];
+}
+/**
+ * Splits a large preformatted (code) element by lines
+ */
+function splitPreformattedElement(element, maxChars) {
+    // Get the text content
+    const textElements = element.elements.filter(e => e.type === 'text');
+    if (textElements.length === 0) {
+        return [element];
+    }
+    const fullText = textElements.map(e => e.type === 'text' ? e.text : '').join('');
+    const lines = fullText.split('\n');
+    if (lines.length <= 1) {
+        // Can't split further
+        return [element];
+    }
+    const result = [];
+    let currentLines = [];
+    const createPreformatted = (text) => ({
+        type: 'rich_text_preformatted',
+        elements: [{ type: 'text', text }],
+        ...(element.border !== undefined ? { border: element.border } : {}),
+    });
+    const estimateSize = (text) => {
+        return JSON.stringify(createPreformatted(text)).length;
+    };
+    for (const line of lines) {
+        const testText = [...currentLines, line].join('\n');
+        if (estimateSize(testText) <= maxChars) {
+            currentLines.push(line);
+        }
+        else {
+            // Flush current lines
+            if (currentLines.length > 0) {
+                result.push(createPreformatted(currentLines.join('\n')));
+                currentLines = [];
+            }
+            // Start new batch with this line
+            currentLines.push(line);
+        }
+    }
+    // Flush remaining
+    if (currentLines.length > 0) {
+        result.push(createPreformatted(currentLines.join('\n')));
+    }
+    return result.length > 0 ? result : [element];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdown-to-slack-blocks",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Convert Markdown to Slack Block Kit JSON format",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -30,7 +30,7 @@
     "rich-text",
     "parser"
   ],
-  "author": "udi",
+  "author": "allx",
   "license": "MIT",
   "repository": {
     "type": "git",