fix(type-annotations): space union separators in type values

.changeset/spaced-union-types.md

@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': patch
+---
+
+Space union separators in type annotation values (`{string|URL}` is now rendered as `string | URL`).

src/utils/type-annotations/__tests__/remark.test.mjs

@@ -28,11 +28,21 @@ describe('remarkTypeAnnotations', () => {
   it('parses multiple annotations in one paragraph', () => {
     assert.deepEqual(valuesIn('{string} and {Buffer|Blob} and {integer}'), [
       'string',
-      'Buffer|Blob',
+      'Buffer | Blob',
       'integer',
     ]);
   });
 
+  it('spaces union separators, without touching `||`', () => {
+    assert.deepEqual(valuesIn('Takes {string|URL} or {string  |  URL}.'), [
+      'string | URL',
+      'string | URL',
+    ]);
+    assert.deepEqual(valuesIn("Defaults to {req.url || '/'}."), [
+      "req.url || '/'",
+    ]);
+  });
+
   it('supports nested braces (object literal types)', () => {
     assert.deepEqual(valuesIn('Takes {Record<string, {a: number}>} maps.'), [
       'Record<string, {a: number}>',
@@ -62,7 +72,7 @@ describe('remarkTypeAnnotations', () => {
       '| `flag` | {string\\|number} |',
     ].join('\n');
 
-    assert.deepEqual(valuesIn(markdown), ['string|number']);
+    assert.deepEqual(valuesIn(markdown), ['string | number']);
   });
 
   it('normalizes interior line breaks to spaces', () => {
@@ -122,6 +132,6 @@ describe('remarkTypeAnnotations', () => {
       processor.parse('Returns: {Promise<Buffer|string>} on success.')
     );
 
-    assert.match(output, /\{Promise<Buffer\|string>\}/);
+    assert.match(output, /\{Promise<Buffer \| string>\}/);
   });
 });

src/utils/type-annotations/mdast.mjs

@@ -5,12 +5,17 @@
 // and the mandatory `\|` inside GFM table cells must be decoded here.
 const CHARACTER_ESCAPE = /\\([!-/:-@[-`{-~])/g;
 
+// A single union separator, with any surrounding whitespace. Lookarounds
+// exclude `||` (logical OR in default-value prose).
+const UNION_SEPARATOR = /(?<!\|)\s*\|\s*(?!\|)/g;
+
 /**
  * Creates the mdast-util-from-markdown extension that compiles
  * `typeAnnotation` tokens into `{ type: 'typeAnnotation', value }` nodes.
  *
  * The stored `value` is the canonical, single-line, unescaped TypeScript type
- * text; link offsets computed later are relative to it.
+ * text with union separators spaced (`A | B`); link offsets computed later
+ * are relative to it.
  *
  * @returns {import('mdast-util-from-markdown').Extension}
  */
@@ -46,7 +51,8 @@ export const typeAnnotationFromMarkdown = () => ({
       node.value = node.value
         .replace(/\s+/g, ' ')
         .trim()
-        .replace(CHARACTER_ESCAPE, '$1');
+        .replace(CHARACTER_ESCAPE, '$1')
+        .replace(UNION_SEPARATOR, ' | ');
 
       this.exit(token);
     },