@dita-viewer/core 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -224,7 +224,7 @@ function expandMfenced(node) {
224
224
  // spurious extra separator characters for the whitespace "children"
225
225
  // surrounding the real one.
226
226
  const items = (node.children || [])
227
- .filter((c) => c.type !== 'text' || (c.text || '').trim() !== '')
227
+ .filter((c) => c.type !== 'comment' && (c.type !== 'text' || (c.text || '').trim() !== ''))
228
228
  .map(serializeForeignContent);
229
229
  let inner = '';
230
230
  if (open !== '')
@@ -242,6 +242,14 @@ function expandMfenced(node) {
242
242
  inner += `<mo>${escapeHtml(close)}</mo>`;
243
243
  return `<mrow>${inner}</mrow>`;
244
244
  }
245
+ /**
246
+ * True when the element has any child that is author content. An XML comment
247
+ * is a node of its own in the parse tree (shown in place by the renderer) but
248
+ * is never content: `<xref href="a.dita"><!-- note --></xref>` has no label.
249
+ */
250
+ function hasContentChildren(node) {
251
+ return (node.children || []).some((c) => c.type !== 'comment');
252
+ }
245
253
  function serializeForeignContent(node) {
246
254
  if (node.type === 'text')
247
255
  return escapeHtml(node.text || '');
@@ -776,6 +784,10 @@ export const BASE_TYPE_RENDERERS = {
776
784
  },
777
785
  'topic/pre': (_node, ctx, renderChildren) => `<pre class="pre preformatted">${renderChildren(_node, ctx)}</pre>`,
778
786
  'topic/xref': (node, ctx, renderChildren) => {
787
+ // An xref whose only child is an XML comment (<!-- Pull title from ... -->)
788
+ // has no author-written label: it falls back to the resolved title / href
789
+ // exactly as an empty one does, rather than showing the comment as its
790
+ // link text. hasContentChildren() is the single place that says so.
779
791
  const href = getAttr(node, 'href') || '';
780
792
  // No target at all: an xref with neither @href nor a keyref that
781
793
  // resolves to one. Dropping the element silently (the old behaviour)
@@ -784,7 +796,7 @@ export const BASE_TYPE_RENDERERS = {
784
796
  // when it does not (the same treatment topic/ph gives an unresolved
785
797
  // keyref) -- means a broken xref reads as one instead of vanishing.
786
798
  if (!href) {
787
- if (node.children.length > 0) {
799
+ if (hasContentChildren(node)) {
788
800
  const content = renderChildren(node, ctx);
789
801
  const keyref = getAttr(node, 'keyref');
790
802
  return keyref
@@ -797,7 +809,7 @@ export const BASE_TYPE_RENDERERS = {
797
809
  return `<span class="xref unresolved-keyref" title="Unresolved key: ${escapeAttr(keyref)}">[${escapeAttr(keyref)}]</span>`;
798
810
  }
799
811
  let content;
800
- if (node.children.length > 0) {
812
+ if (hasContentChildren(node)) {
801
813
  content = renderChildren(node, ctx);
802
814
  }
803
815
  else if (href.startsWith('#')) {
@@ -459,10 +459,15 @@ export function isDitamapRef(node) {
459
459
  const pathPart = href.split('#')[0].toLowerCase();
460
460
  return pathPart.endsWith('.ditamap') || node.attributes?.format === 'ditamap';
461
461
  }
462
- function collectEntriesRecursive(node, depth, result, resolveKey, roleLabel, inheritedProcessingRole = 'normal') {
462
+ function collectEntriesRecursive(node, depth, result, resolveKey, roleLabel, inheritedProcessingRole = 'normal', outerScopes = [[]]) {
463
463
  if (node.type !== 'element')
464
464
  return;
465
465
  const baseType = node.baseType;
466
+ // A keyscope names a scope for the element carrying it and everything below.
467
+ const keyscope = getAttr(node, 'keyscope');
468
+ const scopeChains = keyscope
469
+ ? outerScopes.flatMap((chain) => keyscope.trim().split(/\s+/).filter(Boolean).map((name) => chain.concat(name)))
470
+ : outerScopes;
466
471
  // Skip reltable and its children
467
472
  if (baseType === 'map/reltable')
468
473
  return;
@@ -482,7 +487,7 @@ function collectEntriesRecursive(node, depth, result, resolveKey, roleLabel, inh
482
487
  // level deeper just because expandDitamapRefs happened to splice them
483
488
  // in as DOM children of this wrapper node.
484
489
  for (const child of node.children || []) {
485
- collectEntriesRecursive(child, depth, result, resolveKey, roleLabel, inheritedProcessingRole);
490
+ collectEntriesRecursive(child, depth, result, resolveKey, roleLabel, inheritedProcessingRole, scopeChains);
486
491
  }
487
492
  return;
488
493
  }
@@ -519,21 +524,22 @@ function collectEntriesRecursive(node, depth, result, resolveKey, roleLabel, inh
519
524
  // been) serves no one.
520
525
  role: effectiveProcessingRole === 'resource-only' ? undefined : roleLabel(node.tagName, depth),
521
526
  resourceOnly: effectiveProcessingRole === 'resource-only',
527
+ scopeChains,
522
528
  });
523
529
  // Recurse children at depth+1
524
530
  for (const child of node.children || []) {
525
- collectEntriesRecursive(child, depth + 1, result, resolveKey, roleLabel, effectiveProcessingRole);
531
+ collectEntriesRecursive(child, depth + 1, result, resolveKey, roleLabel, effectiveProcessingRole, scopeChains);
526
532
  }
527
533
  }
528
534
  else if (baseType === 'map/topicgroup' || baseType === 'map/bookmap-structural') {
529
535
  // topicgroup / bookmap-structural: no entry itself, but recurse at same depth
530
536
  for (const child of node.children || []) {
531
- collectEntriesRecursive(child, depth, result, resolveKey, roleLabel, effectiveProcessingRole);
537
+ collectEntriesRecursive(child, depth, result, resolveKey, roleLabel, effectiveProcessingRole, scopeChains);
532
538
  }
533
539
  }
534
540
  else {
535
541
  for (const child of node.children || []) {
536
- collectEntriesRecursive(child, depth, result, resolveKey, roleLabel, effectiveProcessingRole);
542
+ collectEntriesRecursive(child, depth, result, resolveKey, roleLabel, effectiveProcessingRole, scopeChains);
537
543
  }
538
544
  }
539
545
  }
@@ -491,10 +491,70 @@ function renderConrefRange(node, range, context, conref) {
491
491
  })
492
492
  .join('');
493
493
  }
494
+ // Parents whose content model is element-only, so a comment written inside
495
+ // them sits between blocks rather than inside a sentence and should get a
496
+ // block of its own. Everything else -- p, ph, li, entry, title, note text --
497
+ // holds mixed content, where an inline <span> is both valid and what the
498
+ // author saw. This is the same inline/block distinction profiling markers
499
+ // make (INLINE_PROFILING_BASETYPES), stated the other way round: there,
500
+ // inline was the short list; here the inline cases are the majority, and
501
+ // getting it wrong on the block side is the harmless direction (a comment on
502
+ // its own line inside a phrase) while a <div> inside a <p> would make the
503
+ // browser close the paragraph and split the sentence around it.
504
+ const BLOCK_COMMENT_PARENTS = new Set([
505
+ 'topic/body',
506
+ 'topic/section',
507
+ 'topic/example',
508
+ 'topic/fig',
509
+ 'topic/div',
510
+ 'topic/bodydiv',
511
+ 'topic/sectiondiv',
512
+ 'topic/topic',
513
+ 'topic/abstract',
514
+ 'topic/related-links',
515
+ 'topic/imagemap',
516
+ // List containers: a comment written between two <li>s is not part of
517
+ // either item's sentence, and an inline span there would be a stray
518
+ // fragment of the previous item.
519
+ 'topic/ul',
520
+ 'topic/ol',
521
+ 'topic/sl',
522
+ 'topic/dl',
523
+ ]);
524
+ /**
525
+ * An XML comment, shown in the flow at the position it was authored in --
526
+ * Oxygen's Author mode shows the comment text the same way, instead of the
527
+ * reader having to open the source. The text is the comment's inner content
528
+ * with the `<!-- -->` delimiters stripped: the delimiters are markup, and a
529
+ * comment's *text* is what the author wanted read. data-dita-tagname makes the
530
+ * story explicit through the Tags toggle (its tooltip reads "comment"), and
531
+ * data-line* keeps preview clicks and scroll-sync landing on the comment's own
532
+ * source lines -- its range spans `<!--` through `-->`.
533
+ *
534
+ * An empty or whitespace-only comment renders nothing: it is a spelling of
535
+ * "nothing here", and an empty box in the page would only be noise.
536
+ */
537
+ function renderComment(node, context) {
538
+ const text = (node.comment || '').replace(/\r\n?/g, '\n').trim();
539
+ if (!text)
540
+ return '';
541
+ const block = BLOCK_COMMENT_PARENTS.has(context.parentBaseType || '');
542
+ const tag = block ? 'div' : 'span';
543
+ const cls = block ? 'dv-comment dv-comment--block' : 'dv-comment';
544
+ const range = node.sourceRange;
545
+ return (`<${tag} class="${cls}" data-dita-tagname="comment"` +
546
+ ` data-line="${range.startLine}" data-end-line="${range.endLine}"` +
547
+ ` data-start-col="${range.startCol}" data-end-col="${range.endCol}">` +
548
+ escapeHtml(text) +
549
+ `</${tag}>`);
550
+ }
494
551
  export function renderElement(node, context, conrefMark) {
495
552
  if (node.type === 'text') {
496
553
  return escapeHtml(node.text || '');
497
554
  }
555
+ if (node.type === 'comment') {
556
+ return renderComment(node, context);
557
+ }
498
558
  const conref = node.attributes?.conref;
499
559
  const conrefend = node.attributes?.conrefend;
500
560
  if (conref && conrefend && context.resolveConrefRange && !context.conrefChain?.has(conref)) {
@@ -512,8 +572,23 @@ export function renderElement(node, context, conrefMark) {
512
572
  // The element's own conref wins over a mark handed down by a range.
513
573
  return renderEffectiveNode(effectiveNode, context, resolved.chainKey, resolved.mark ?? conrefMark);
514
574
  }
575
+ // Parents whose children must not include a comment span or block:
576
+ // - table machinery: a <span>/<div> directly inside <table>, <tbody> or <tr>
577
+ // is foster-parented by the browser to just before the whole table, so the
578
+ // comment would show up away from where it was written;
579
+ // - preformatted blocks: the comment's text would read, and copy, as code;
580
+ // - titles: the heading's text feeds the outline / table of contents.
581
+ // Keyed by the baseType of the element being rendered (the real parent), not
582
+ // by the overloaded context.parentBaseType.
583
+ const NO_COMMENT_CHILDREN = new Set([
584
+ 'topic/table', 'topic/tgroup', 'topic/thead', 'topic/tbody', 'topic/row',
585
+ 'topic/simpletable', 'topic/sthead', 'topic/strow',
586
+ 'topic/pre', 'topic/codeblock', 'topic/lines',
587
+ 'topic/title',
588
+ ]);
515
589
  function renderChildren(node, context) {
516
- const children = node.children || [];
590
+ const skipComments = !!node.baseType && NO_COMMENT_CHILDREN.has(node.baseType);
591
+ const children = (node.children || []).filter((c) => !(skipComments && c.type === 'comment'));
517
592
  // Resolved key text can leave CJK and Latin glued together (`打开` + `ABC`).
518
593
  // Insert a display-only space outside the key element; the source is untouched.
519
594
  const spacing = computeKeyrefSpacing(children, node.baseType, context.resolveKey);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dita-viewer/core",
3
- "version": "0.2.3",
3
+ "version": "0.2.4",
4
4
  "description": "Host-neutral DITA parsing and HTML rendering core, shared by the VS Code DITA Viewer and obsidian-dita.",
5
5
  "keywords": [
6
6
  "dita",
@@ -51,6 +51,9 @@
51
51
  --color-profiling-label-text: #2a3a12;
52
52
  --color-indexterm-chip-bg: #e6f0fa;
53
53
  --color-indexterm-chip-text: #2c5282;
54
+ --color-comment-bg: #efefef;
55
+ --color-comment-border: #c4c4c4;
56
+ --color-comment-text: #6b6b6b;
54
57
  --color-menucascade-arrow: #767676;
55
58
  }
56
59
 
@@ -71,6 +74,9 @@
71
74
  --color-profiling-label-text: #eef7dc;
72
75
  --color-indexterm-chip-bg: #1f2f42;
73
76
  --color-indexterm-chip-text: #9dc4ea;
77
+ --color-comment-bg: #2b2b2b;
78
+ --color-comment-border: #4d4d4d;
79
+ --color-comment-text: #9a9a9a;
74
80
  --color-menucascade-arrow: #aaaaaa;
75
81
  }
76
82
 
@@ -556,6 +562,30 @@ html.dv-conref-hot [data-conref] *,
556
562
  }
557
563
  .indexterm-chip--ref { font-style: italic; }
558
564
  .indexterm-chip__see { font-style: italic; opacity: 0.85; }
565
+ /* An XML comment's own text, shown where the author wrote it (Oxygen's Author
566
+ mode does the same). Deliberately quiet -- muted colour, no border of its
567
+ own -- because it is not document content: the reader should be able to see
568
+ it, and to skip over it without the page looking broken. Block comments
569
+ (one written between two blocks rather than inside a sentence) get a
570
+ leading rule so the whole run reads as one comment instead of stray text. */
571
+ .dv-comment {
572
+ background: var(--color-comment-bg);
573
+ color: var(--color-comment-text);
574
+ font-style: italic;
575
+ border-radius: 3px;
576
+ padding: 0 0.2em;
577
+ white-space: pre-wrap;
578
+ /* A wrapped inline comment must paint each line's box, not just the first. */
579
+ -webkit-box-decoration-break: clone;
580
+ box-decoration-break: clone;
581
+ }
582
+ .dv-comment--block {
583
+ display: block;
584
+ margin: 0.5em 0;
585
+ padding: 0.15em 0.6em;
586
+ border-left: 3px solid var(--color-comment-border);
587
+ border-radius: 0 3px 3px 0;
588
+ }
559
589
  body.hide-profiling .profiled,
560
590
  .dita-body.hide-profiling .profiled {
561
591
  background: none;