@fusion.dev/helix-core 0.11.0 → 0.12.0

package/custom-elements.json

@@ -4545,6 +4545,14 @@
             "module": "./utils/capture-pointer/capture-pointer.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "closeMarkdown",
+          "declaration": {
+            "name": "closeMarkdown",
+            "module": "./utils/close-markdown/close-markdown.js"
+          }
+        },
         {
           "kind": "js",
           "name": "closestInstance",
@@ -7084,6 +7092,40 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/close-markdown/close-markdown.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "closeMarkdown",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "partial",
+              "type": {
+                "text": "string"
+              }
+            }
+          ],
+          "description": "A prefix of a markdown document, made safe to render as it arrives.\n\n**A streamed answer is a prefix, and a prefix is rarely valid markdown.** The\nmoment a model writes an opening fence, everything after it is code that has\nnot been told it is code: a renderer handed that prefix draws paragraphs,\nthen redraws the whole block when the closing fence lands three seconds\nlater. The same holds for a backtick, a `**`, and a link whose target is\nstill being typed — each renders as punctuation until its partner arrives.\n\nSo this closes what is open. It does not parse markdown and does not render\nit: it returns a string the caller's own renderer can be handed, in which\nevery construct that was opened is also closed.\n\n**What it does not do is remove anything a reader can already read.** The\nexception is a link or image whose brackets are still open, because there is\nno closing that: a target arrives character by character, and `[the docs](ht`\nhas no valid completion that is not a guess at a URL. That fragment is\nwithheld until it is whole, which is the one case where a word appears a beat\nlater than it was received.\n\n**Inside a fence nothing else applies**, which is why closing one returns\nimmediately. The characters in a code block are code: a stray backtick or a\nlone asterisk in a shell command is not an unclosed span, and treating it as\none would append punctuation into somebody's code.\n\n**Underscores are left alone.** `_` opens emphasis in markdown and also sits\ninside `snake_case`, `__init__` and a filename, and a prefix gives no way to\ntell which: closing one turns an identifier into italics for as long as the\nrest of the word takes to arrive, which is worse than the punctuation it was\nmeant to hide. `*` does not have that problem, being punctuation everywhere\nit is not emphasis.\n\nStable across a growing prefix, which is the property that matters: calling\nthis on each frame of a stream cannot make text move that has already\nsettled, because everything it adds is at the end and everything it withholds\nis a fragment that has not been shown yet."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "closeMarkdown",
+          "declaration": {
+            "name": "closeMarkdown",
+            "module": "src/utils/close-markdown/close-markdown.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/closest-instance/closest-instance.ts",

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { type DismissibleElement, MixinDismissible, } from './mixins/mixin-dismi
 export { MixinField, type MixinFieldInterface } from './mixins/mixin-field/mixin-field.js';
 export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
+export { closeMarkdown } from './utils/close-markdown/close-markdown.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
 export { createSheet } from './utils/create-sheet/create-sheet.js';
 export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';

package/dist/index.js

@@ -27,6 +27,7 @@ export { MixinDismissible, } from './mixins/mixin-dismissible/mixin-dismissible.
 export { MixinField } from './mixins/mixin-field/mixin-field.js';
 export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
+export { closeMarkdown } from './utils/close-markdown/close-markdown.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
 export { createSheet } from './utils/create-sheet/create-sheet.js';
 export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';

package/dist/utils/close-markdown/close-markdown.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A prefix of a markdown document, made safe to render as it arrives.
+ *
+ * **A streamed answer is a prefix, and a prefix is rarely valid markdown.** The
+ * moment a model writes an opening fence, everything after it is code that has
+ * not been told it is code: a renderer handed that prefix draws paragraphs,
+ * then redraws the whole block when the closing fence lands three seconds
+ * later. The same holds for a backtick, a `**`, and a link whose target is
+ * still being typed — each renders as punctuation until its partner arrives.
+ *
+ * So this closes what is open. It does not parse markdown and does not render
+ * it: it returns a string the caller's own renderer can be handed, in which
+ * every construct that was opened is also closed.
+ *
+ * **What it does not do is remove anything a reader can already read.** The
+ * exception is a link or image whose brackets are still open, because there is
+ * no closing that: a target arrives character by character, and `[the docs](ht`
+ * has no valid completion that is not a guess at a URL. That fragment is
+ * withheld until it is whole, which is the one case where a word appears a beat
+ * later than it was received.
+ *
+ * **Inside a fence nothing else applies**, which is why closing one returns
+ * immediately. The characters in a code block are code: a stray backtick or a
+ * lone asterisk in a shell command is not an unclosed span, and treating it as
+ * one would append punctuation into somebody's code.
+ *
+ * **Underscores are left alone.** `_` opens emphasis in markdown and also sits
+ * inside `snake_case`, `__init__` and a filename, and a prefix gives no way to
+ * tell which: closing one turns an identifier into italics for as long as the
+ * rest of the word takes to arrive, which is worse than the punctuation it was
+ * meant to hide. `*` does not have that problem, being punctuation everywhere
+ * it is not emphasis.
+ *
+ * Stable across a growing prefix, which is the property that matters: calling
+ * this on each frame of a stream cannot make text move that has already
+ * settled, because everything it adds is at the end and everything it withholds
+ * is a fragment that has not been shown yet.
+ */
+export declare const closeMarkdown: (partial: string) => string;

package/dist/utils/close-markdown/close-markdown.js

@@ -0,0 +1,51 @@
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+const OPEN_TARGET = /!?\[[^\]]*\]\([^)]*$/;
+const OPEN_TEXT = /!?\[[^\]]*$/;
+export const closeMarkdown = (partial) => {
+    if (partial === '') {
+        return partial;
+    }
+    let owed;
+    for (const line of partial.split('\n')) {
+        const found = FENCE.exec(line);
+        if (!found) {
+            continue;
+        }
+        const mark = found[1];
+        if (owed === undefined) {
+            owed = mark;
+        }
+        else if (mark[0] === owed[0] && mark.length >= owed.length) {
+            owed = undefined;
+        }
+    }
+    if (owed !== undefined) {
+        return `${partial}${partial.endsWith('\n') ? '' : '\n'}${owed}`;
+    }
+    const cut = partial.lastIndexOf('\n\n');
+    const head = cut === -1 ? '' : partial.slice(0, cut + 2);
+    let tail = partial.slice(cut === -1 ? 0 : cut + 2);
+    const target = OPEN_TARGET.exec(tail);
+    if (target) {
+        tail = tail.slice(0, target.index);
+    }
+    else {
+        const text = OPEN_TEXT.exec(tail);
+        if (text) {
+            tail = tail.slice(0, text.index);
+        }
+    }
+    const ticks = (tail.match(/`/g) ?? []).length;
+    if (ticks % 2 === 1) {
+        tail += '`';
+    }
+    const strong = (tail.match(/\*\*/g) ?? []).length;
+    if (strong % 2 === 1) {
+        tail += '**';
+    }
+    const single = (tail.match(/(?<!\*)\*(?!\*)/g) ?? []).length;
+    if (single % 2 === 1) {
+        tail += '*';
+    }
+    return head + tail;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,12 +34,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.11.0"
+    "@fusion.dev/helix-icons": "0.12.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.11.0",
-    "@fusion.dev/helix-testing": "0.11.0",
+    "@fusion.dev/helix-cem": "0.12.0",
+    "@fusion.dev/helix-testing": "0.12.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",