@dita-viewer/core 0.2.4 → 0.2.5

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.
@@ -1,4 +1,5 @@
1
1
  import type { MapEntry, RoleLabelFormatter } from './render/mapTypeMap';
2
+ import type { RefErrorTexts } from './render/refErrorTexts';
2
3
  import type { ProfileFilter } from './profiling';
3
4
  export interface BookXmlRenderInput {
4
5
  /** The map's source text. */
@@ -45,6 +46,13 @@ export interface BookXmlRenderInput {
45
46
  * render without touching the disk.
46
47
  */
47
48
  readFile?: (absPath: string) => string;
49
+ /**
50
+ * Localized wording for the broken-reference hints (see
51
+ * BuildRenderContextInput.refErrorTexts). Book/site rendering always
52
+ * surfaces the hints (refErrors is forced on, like markConrefs); a host
53
+ * that shows another language passes its own strings here.
54
+ */
55
+ refErrorTexts?: Partial<RefErrorTexts>;
48
56
  }
49
57
  export interface BookXmlRenderResult {
50
58
  html: string;
@@ -130,6 +130,8 @@ function renderBookXml(input) {
130
130
  bookMembers: members,
131
131
  docFile: absPath,
132
132
  markConrefs: true,
133
+ refErrors: true,
134
+ refErrorTexts: input.refErrorTexts,
133
135
  });
134
136
  if (result.error !== undefined) {
135
137
  sections.push(`<p class="dita-book-error">${escapeHtml(result.error)}</p>`);
@@ -17,3 +17,13 @@ import { KeyDefLookup } from './keySpace';
17
17
  * is missing or unparseable.
18
18
  */
19
19
  export declare function resolveConkeyref(conkeyref: string, defs: KeyDefLookup, loadTopic: (baseDir: string, href: string) => DitaNode | undefined): DitaNode | undefined;
20
+ export type ConkeyrefFailure = 'missingKey' | 'missingFile' | 'parseError' | 'missingId';
21
+ /**
22
+ * Why a conkeyref pulls nothing, in the order resolveConkeyref checks:
23
+ * the key is undefined or has no href; its file is missing or not
24
+ * well-formed (`fileExists` tells the two apart, as loadTopic cannot); the
25
+ * addressed id is absent. Undefined when the reference resolves. Kept next
26
+ * to resolveConkeyref and built on the same steps so the two cannot
27
+ * disagree about what "resolves" means.
28
+ */
29
+ export declare function diagnoseConkeyref(conkeyref: string, defs: KeyDefLookup, loadTopic: (baseDir: string, href: string) => DitaNode | undefined, fileExists: (baseDir: string, href: string) => boolean): ConkeyrefFailure | undefined;
@@ -25,6 +25,8 @@
25
25
  // switches conkeyref targets for free.
26
26
  Object.defineProperty(exports, "__esModule", { value: true });
27
27
  exports.resolveConkeyref = resolveConkeyref;
28
+ exports.diagnoseConkeyref = diagnoseConkeyref;
29
+ const refTargets_1 = require("../render/refTargets");
28
30
  /**
29
31
  * Addressing inside the key's target topic: the whole topic when the value has
30
32
  * only the key name, otherwise the last path segment (the element id, for both
@@ -105,4 +107,34 @@ function resolveConkeyref(conkeyref, defs, loadTopic) {
105
107
  return root;
106
108
  return findElementById(root, targetId);
107
109
  }
110
+ /**
111
+ * Why a conkeyref pulls nothing, in the order resolveConkeyref checks:
112
+ * the key is undefined or has no href; its file is missing or not
113
+ * well-formed (`fileExists` tells the two apart, as loadTopic cannot); the
114
+ * addressed id is absent. Undefined when the reference resolves. Kept next
115
+ * to resolveConkeyref and built on the same steps so the two cannot
116
+ * disagree about what "resolves" means.
117
+ */
118
+ function diagnoseConkeyref(conkeyref, defs, loadTopic, fileExists) {
119
+ const { keyName, elementId } = parseConkeyref(conkeyref);
120
+ if (!keyName)
121
+ return undefined;
122
+ const def = defs.get(keyName);
123
+ if (!def || !def.href)
124
+ return 'missingKey';
125
+ // A keydef may name a non-local or non-DITA resource (scope="external"
126
+ // href="https://...", format="pdf" href="manual.pdf"): keySpace records
127
+ // hrefs without filtering scope/format, so the exclusion lives here, from
128
+ // the same rule makeRefErrorResolver applies to a direct ref. The fragment
129
+ // is stripped first -- it is the target format's own, not a DITA id.
130
+ if ((0, refTargets_1.isNonDitaTarget)(def.href.split('#')[0]))
131
+ return undefined;
132
+ const root = loadTopic(def.baseDir, def.href);
133
+ if (!root)
134
+ return fileExists(def.baseDir, def.href) ? 'parseError' : 'missingFile';
135
+ const targetId = elementId ?? hrefFragmentTarget(def.href);
136
+ if (!targetId)
137
+ return undefined;
138
+ return findElementById(root, targetId) ? undefined : 'missingId';
139
+ }
108
140
  //# sourceMappingURL=conkeyref.js.map
@@ -1,4 +1,6 @@
1
1
  import { DitaNode } from '../parser/domTypes';
2
+ import { RefErrorTexts } from '../render/refErrorTexts';
3
+ import { URL_SCHEME_RE } from '../render/refTargets';
2
4
  export declare const IMAGE_DIMENSIONS_CACHE_MAX = 1000;
3
5
  export declare function clearImageDimensionsCache(): void;
4
6
  export declare function readImageDimensions(filePath: string): {
@@ -22,6 +24,31 @@ export declare function makeFileCache(docDir: string): {
22
24
  };
23
25
  export declare function makeConrefResolver(docDir: string, ownRoot?: DitaNode, sharedCache?: ReturnType<typeof makeFileCache>): (conref: string, from?: DitaNode) => DitaNode | undefined;
24
26
  export declare function makeConrefRangeResolver(docDir: string, ownRoot?: DitaNode, sharedCache?: ReturnType<typeof makeFileCache>): (conref: string, conrefend: string) => DitaNode[] | undefined;
27
+ /**
28
+ * Default broken-reference diagnosis for RenderContext.refError: the
29
+ * three-state reason a local reference can fail with, in the order the
30
+ * resolver chain itself checks --
31
+ * missing file -- nothing at the referenced path in the closure;
32
+ * parse error -- the file is there but is not well-formed XML (the
33
+ * common review case: an author broke a DIFFERENT file);
34
+ * missing id -- the file parses but #topicId/elementId names no id.
35
+ * Returns undefined for a reference that resolves, and for ones it will
36
+ * not diagnose at all: external URLs, absolute paths, and hrefs that are
37
+ * neither a fragment nor a DITA-shaped file path (a bare id is not a
38
+ * filename to probe). Same-document fragments (#id, #./topicId/id) are
39
+ * checked against ownRoot without touching the filesystem.
40
+ *
41
+ * Rides the shared file cache so a target already loaded for conref/title
42
+ * resolution is not parsed twice, and every probed path -- missing ones
43
+ * included -- lands in touchedFiles() for the caller's dependency set:
44
+ * creating the missing target is exactly the change that must invalidate
45
+ * a cached render. The cache memoizes missing and unparsable alike as
46
+ * undefined, so existsSync is what tells the two apart.
47
+ *
48
+ * The renderer only presents the returned reason (see refErrorTexts.ts);
49
+ * a host with its own diagnostic rules supplies its own callback instead.
50
+ */
51
+ export declare function makeRefErrorResolver(docDir: string, ownRoot?: DitaNode, sharedCache?: ReturnType<typeof makeFileCache>, texts?: RefErrorTexts): (ref: string) => string | undefined;
25
52
  export declare function makeFileTitleResolver(docDir: string, sharedCache?: ReturnType<typeof makeFileCache>, resolveKey?: (key: string) => string | undefined): (href: string) => string | undefined;
26
53
  export declare const DEFAULT_NOTE_LABELS: Record<string, string>;
27
54
  export declare const ZH_NOTE_LABELS: Record<string, string>;
@@ -32,7 +59,7 @@ export declare function detectNoteLabels(root: DitaNode, uiLanguage?: string): R
32
59
  * its own (much smaller) two-language set. */
33
60
  export declare function detectIndexLabel(root: DitaNode, uiLanguage?: string): string;
34
61
  export type FileReader = (path: string, encoding: 'utf-8') => string;
35
- export declare const URL_SCHEME_RE: RegExp;
62
+ export { URL_SCHEME_RE };
36
63
  /**
37
64
  * Builds the render context's isInCurrentBook resolver: given a cross-file
38
65
  * xref's raw href, return the absolute path of the target IF it is one of
@@ -6,6 +6,7 @@ exports.readImageDimensions = readImageDimensions;
6
6
  exports.makeFileCache = makeFileCache;
7
7
  exports.makeConrefResolver = makeConrefResolver;
8
8
  exports.makeConrefRangeResolver = makeConrefRangeResolver;
9
+ exports.makeRefErrorResolver = makeRefErrorResolver;
9
10
  exports.makeFileTitleResolver = makeFileTitleResolver;
10
11
  exports.detectNoteLabels = detectNoteLabels;
11
12
  exports.detectIndexLabel = detectIndexLabel;
@@ -27,6 +28,9 @@ const fs_1 = require("fs");
27
28
  const path_1 = require("path");
28
29
  const ditaParser_1 = require("../parser/ditaParser");
29
30
  const mapTypeMap_1 = require("../render/mapTypeMap");
31
+ const refErrorTexts_1 = require("../render/refErrorTexts");
32
+ const refTargets_1 = require("../render/refTargets");
33
+ Object.defineProperty(exports, "URL_SCHEME_RE", { enumerable: true, get: function () { return refTargets_1.URL_SCHEME_RE; } });
30
34
  const sourceText_1 = require("./sourceText");
31
35
  // ── Image dimensions (for reserving layout space before the image loads) ──
32
36
  //
@@ -438,13 +442,74 @@ function makeConrefRangeResolver(docDir, ownRoot, sharedCache) {
438
442
  return run;
439
443
  };
440
444
  }
445
+ /**
446
+ * Default broken-reference diagnosis for RenderContext.refError: the
447
+ * three-state reason a local reference can fail with, in the order the
448
+ * resolver chain itself checks --
449
+ * missing file -- nothing at the referenced path in the closure;
450
+ * parse error -- the file is there but is not well-formed XML (the
451
+ * common review case: an author broke a DIFFERENT file);
452
+ * missing id -- the file parses but #topicId/elementId names no id.
453
+ * Returns undefined for a reference that resolves, and for ones it will
454
+ * not diagnose at all: external URLs, absolute paths, and hrefs that are
455
+ * neither a fragment nor a DITA-shaped file path (a bare id is not a
456
+ * filename to probe). Same-document fragments (#id, #./topicId/id) are
457
+ * checked against ownRoot without touching the filesystem.
458
+ *
459
+ * Rides the shared file cache so a target already loaded for conref/title
460
+ * resolution is not parsed twice, and every probed path -- missing ones
461
+ * included -- lands in touchedFiles() for the caller's dependency set:
462
+ * creating the missing target is exactly the change that must invalidate
463
+ * a cached render. The cache memoizes missing and unparsable alike as
464
+ * undefined, so existsSync is what tells the two apart.
465
+ *
466
+ * The renderer only presents the returned reason (see refErrorTexts.ts);
467
+ * a host with its own diagnostic rules supplies its own callback instead.
468
+ */
469
+ function makeRefErrorResolver(docDir, ownRoot, sharedCache, texts = refErrorTexts_1.DEFAULT_REF_ERROR_TEXTS) {
470
+ const cache = sharedCache ?? makeFileCache(docDir);
471
+ return (ref) => {
472
+ if (!ref)
473
+ return undefined;
474
+ const hashIdx = ref.indexOf('#');
475
+ const filePath = hashIdx >= 0 ? ref.substring(0, hashIdx) : ref;
476
+ // "#./topicId/elementId" shorthand: strip the same-document marker
477
+ // before splitting, the same rule makeConrefRangeResolver applies.
478
+ const idPart = hashIdx >= 0 ? ref.substring(hashIdx + 1).replace(/^\.\/+/, '') : '';
479
+ const parts = idPart.split('/');
480
+ const elementId = parts.length > 1 ? parts[1] : parts[0];
481
+ // URL, absolute path, or a web document (guide.html#sec): not a local
482
+ // DITA target, so never probed -- see isNonDitaTarget.
483
+ if ((0, refTargets_1.isNonDitaTarget)(filePath))
484
+ return undefined;
485
+ if (!filePath) {
486
+ // Same-document fragment: the id must exist in the document itself.
487
+ if (!idPart || !elementId || !ownRoot)
488
+ return undefined;
489
+ return cache.findElementById(ownRoot, elementId) ? undefined : texts.missingId;
490
+ }
491
+ // No fragment: only a DITA-shaped file path is a file-level reference
492
+ // worth probing (a bare word is not a filename). With a fragment the
493
+ // file part is always checked, whatever its extension -- conref/xref
494
+ // targets are .dita/.xml in practice but the resolver loads any path.
495
+ if (hashIdx < 0 && !/\.(dita|xml|ditamap)$/i.test(filePath))
496
+ return undefined;
497
+ const abs = (0, path_1.resolve)(docDir, decodeHrefPart(filePath));
498
+ const root = cache.loadAbsPath(abs);
499
+ if (!root)
500
+ return (0, fs_1.existsSync)(abs) ? texts.parseError : texts.missingFile;
501
+ if (!elementId)
502
+ return undefined;
503
+ return cache.findElementById(root, elementId) ? undefined : texts.missingId;
504
+ };
505
+ }
441
506
  function makeFileTitleResolver(docDir, sharedCache, resolveKey) {
442
507
  const cache = sharedCache ?? makeFileCache(docDir);
443
508
  return (href) => {
444
509
  // Only local relative references can be resolved from disk — never probe
445
510
  // the filesystem for external URLs or absolute paths (on Windows an
446
511
  // https:// href would otherwise resolve to a junk docDir\https:\ path).
447
- if (!href || exports.URL_SCHEME_RE.test(href) || (0, path_1.isAbsolute)(href))
512
+ if (!href || refTargets_1.URL_SCHEME_RE.test(href) || (0, path_1.isAbsolute)(href))
448
513
  return undefined;
449
514
  const hashIdx = href.indexOf('#');
450
515
  if (hashIdx < 0) {
@@ -524,7 +589,6 @@ function detectIndexLabel(root, uiLanguage) {
524
589
  const lang = root.attributes?.['xml:lang'] || uiLanguage || '';
525
590
  return lang.startsWith('zh') ? '\u7d22\u5f15' : 'Index';
526
591
  }
527
- exports.URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
528
592
  /**
529
593
  * Builds the render context's isInCurrentBook resolver: given a cross-file
530
594
  * xref's raw href, return the absolute path of the target IF it is one of
@@ -537,7 +601,7 @@ exports.URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
537
601
  */
538
602
  function makeIsInCurrentBook(docDir, bookMembers) {
539
603
  return (href) => {
540
- if (!href || exports.URL_SCHEME_RE.test(href) || (0, path_1.isAbsolute)(href))
604
+ if (!href || refTargets_1.URL_SCHEME_RE.test(href) || (0, path_1.isAbsolute)(href))
541
605
  return undefined;
542
606
  const pathPart = href.split('#')[0];
543
607
  if (!pathPart)
@@ -567,7 +631,7 @@ function isLocalHref(href, scope) {
567
631
  return false;
568
632
  if (scope === 'external' || scope === 'peer')
569
633
  return false;
570
- if (exports.URL_SCHEME_RE.test(href))
634
+ if (refTargets_1.URL_SCHEME_RE.test(href))
571
635
  return false;
572
636
  if ((0, path_1.isAbsolute)(href))
573
637
  return false;
@@ -1,5 +1,6 @@
1
1
  import { DitaNode } from '../parser/domTypes';
2
2
  import { RenderContext } from '../render/renderer';
3
+ import { RefErrorTexts } from '../render/refErrorTexts';
3
4
  import { KeyHrefDef } from './keySpace';
4
5
  export interface BuildRenderContextInput {
5
6
  /** Directory hrefs in this document resolve against (== RenderContext.documentDir). */
@@ -58,6 +59,23 @@ export interface BuildRenderContextInput {
58
59
  clickableExternalXrefs?: boolean;
59
60
  /** Book / site only: sink that records every file the render read. */
60
61
  collectDependencies?: Set<string>;
62
+ /**
63
+ * Opt-in: wire RenderContext.refError with the default three-state
64
+ * diagnosis (makeRefErrorResolver) so a conref that pulls nothing renders
65
+ * as a placeholder chip and an empty xref with a broken target as a
66
+ * .xref-broken marker, instead of silently empty/link-shaped output.
67
+ * Preview and diff paths set this; "Export as HTML" does not -- a shipped
68
+ * document has no editing context for the hints, the same rule
69
+ * suppressIndexterm and markConrefs follow.
70
+ */
71
+ refErrors?: boolean;
72
+ /**
73
+ * Localized wording for the refError hints, merged over the English
74
+ * defaults (DEFAULT_REF_ERROR_TEXTS). The host fills these from its own
75
+ * string catalog -- the VS Code extension via vscode.l10n.t -- so the
76
+ * factory itself stays free of locale logic, like noteLabels.
77
+ */
78
+ refErrorTexts?: Partial<RefErrorTexts>;
61
79
  }
62
80
  export interface BuiltRenderContext {
63
81
  ctx: RenderContext;
@@ -23,8 +23,10 @@
23
23
  // - suppressIndexterm: only the export path sets it.
24
24
  Object.defineProperty(exports, "__esModule", { value: true });
25
25
  exports.buildRenderContext = buildRenderContext;
26
+ const fs_1 = require("fs");
26
27
  const path_1 = require("path");
27
28
  const refResolvers_1 = require("./refResolvers");
29
+ const refErrorTexts_1 = require("../render/refErrorTexts");
28
30
  const keySpace_1 = require("./keySpace");
29
31
  const conkeyref_1 = require("./conkeyref");
30
32
  function buildRenderContext(input) {
@@ -83,6 +85,14 @@ function buildRenderContext(input) {
83
85
  ctx.isInCurrentBook = (0, refResolvers_1.makeIsInCurrentBook)(docDir, input.bookMembers);
84
86
  if (input.clickableExternalXrefs)
85
87
  ctx.clickableExternalXrefs = true;
88
+ if (input.refErrors) {
89
+ const texts = { ...refErrorTexts_1.DEFAULT_REF_ERROR_TEXTS, ...input.refErrorTexts };
90
+ ctx.refErrorTexts = texts;
91
+ // Same shared cache as the conref/title resolvers: a target probed here
92
+ // is usually one they already loaded, and every probe (missing files
93
+ // included) joins touchedFiles for the caller's dependency set.
94
+ ctx.refError = (0, refResolvers_1.makeRefErrorResolver)(docDir, ownRoot, fileCache, texts);
95
+ }
86
96
  // conkeyref rides on the same file cache: a key's href resolves against the
87
97
  // map that defined it (baseDir), not the topic being rendered, so it needs
88
98
  // the absolute-path loader rather than the docDir-relative conref resolver.
@@ -137,6 +147,16 @@ function buildRenderContext(input) {
137
147
  fileCache.noteOrigin(el, lastLoaded);
138
148
  return el;
139
149
  };
150
+ // Only with a key space (this block): a topic previewed with no map has
151
+ // no keys at all, and "key is not defined" there would flag every
152
+ // conkeyref for a reason the author cannot act on.
153
+ if (input.refErrors) {
154
+ const texts = { ...refErrorTexts_1.DEFAULT_REF_ERROR_TEXTS, ...input.refErrorTexts };
155
+ ctx.conkeyrefError = (conkeyref) => {
156
+ const failure = (0, conkeyref_1.diagnoseConkeyref)(conkeyref, keyDefs, loadTopic, (baseDir, href) => (0, fs_1.existsSync)((0, path_1.resolve)(baseDir, (0, refResolvers_1.decodeHrefPart)(href.split('#')[0]))));
157
+ return failure === undefined ? undefined : texts[failure];
158
+ };
159
+ }
140
160
  }
141
161
  // One hop further along a reference chain, resolved relative to the file
142
162
  // that holds `from`. conkeyref wins over conref when it resolves, the same
@@ -1,4 +1,5 @@
1
1
  import { DitaNode } from '../parser/domTypes';
2
+ import type { RefErrorTexts } from '../render/refErrorTexts';
2
3
  export declare function collectText(node: DitaNode): string;
3
4
  export declare function buildTitleMap(root: DitaNode): Map<string, string>;
4
5
  export interface TopicRenderInput {
@@ -46,6 +47,13 @@ export interface TopicRenderInput {
46
47
  * which only ever serves previews, turns it on.
47
48
  */
48
49
  markConrefs?: boolean;
50
+ /** See BuildRenderContextInput.refErrors -- passed through untouched.
51
+ * renderTopicCached (previews only) forces it on, like markConrefs. */
52
+ refErrors?: boolean;
53
+ /** See BuildRenderContextInput.refErrorTexts -- the host's localized
54
+ * wording for the broken-reference hints. Part of renderTopicCached's
55
+ * cache key: the same topic renders different hint text per locale. */
56
+ refErrorTexts?: Partial<RefErrorTexts>;
49
57
  }
50
58
  export interface TopicRenderResult {
51
59
  html: string;
@@ -93,6 +101,10 @@ export interface TopicXmlRenderInput {
93
101
  */
94
102
  docFile?: string;
95
103
  markConrefs?: boolean;
104
+ /** See TopicRenderInput.refErrors. */
105
+ refErrors?: boolean;
106
+ /** See TopicRenderInput.refErrorTexts. */
107
+ refErrorTexts?: Partial<RefErrorTexts>;
96
108
  /** See BuildRenderContextInput.keyScope. */
97
109
  keyScope?: string[][];
98
110
  }
@@ -48,7 +48,7 @@ function buildTitleMap(root) {
48
48
  return map;
49
49
  }
50
50
  function renderTopicXml(input) {
51
- const { xml, docDir, keyMap, asWebviewUri, headingLevel, uiLanguage, suppressIndexterm, collectDependencies, bookMembers, clickableExternalXrefs, docFile, markConrefs, keyScope } = input;
51
+ const { xml, docDir, keyMap, asWebviewUri, headingLevel, uiLanguage, suppressIndexterm, collectDependencies, bookMembers, clickableExternalXrefs, docFile, markConrefs, refErrors, refErrorTexts, keyScope } = input;
52
52
  try {
53
53
  const preprocessedXml = (0, ditaParser_1.preprocessEntities)(xml);
54
54
  const ditaDoc = (0, ditaParser_1.parseDita)(preprocessedXml);
@@ -72,6 +72,8 @@ function renderTopicXml(input) {
72
72
  collectDependencies,
73
73
  docFile,
74
74
  markConrefs,
75
+ refErrors,
76
+ refErrorTexts,
75
77
  keyScope,
76
78
  });
77
79
  const html = (0, renderer_1.renderDocument)(ditaDoc.root, ctx);
@@ -89,7 +91,7 @@ function renderTopicXml(input) {
89
91
  }
90
92
  }
91
93
  function renderTopicToHtml(input) {
92
- const { filePath, keyMap, asWebviewUri, headingLevel, uiLanguage, suppressIndexterm, collectDependencies, bookMembers, clickableExternalXrefs, markConrefs, keyScope } = input;
94
+ const { filePath, keyMap, asWebviewUri, headingLevel, uiLanguage, suppressIndexterm, collectDependencies, bookMembers, clickableExternalXrefs, markConrefs, refErrors, refErrorTexts, keyScope } = input;
93
95
  try {
94
96
  if (!(0, fs_1.existsSync)(filePath)) {
95
97
  return { html: '', error: `File not found: ${filePath}` };
@@ -111,6 +113,8 @@ function renderTopicToHtml(input) {
111
113
  clickableExternalXrefs,
112
114
  docFile: filePath,
113
115
  markConrefs,
116
+ refErrors,
117
+ refErrorTexts,
114
118
  keyScope,
115
119
  });
116
120
  return { html: result.html, title: result.title, error: result.error };
@@ -281,7 +285,12 @@ function dropOldestTopicEntry() {
281
285
  * different key text in each, so a hit from the other scope would be wrong.
282
286
  */
283
287
  function renderTopicCached(input) {
284
- const key = `${input.filePath}\u0000${input.headingLevel}\u0000${input.keyScope ? JSON.stringify(input.keyScope) : ''}`;
288
+ // The hint wording is part of the key: two locales render different chip
289
+ // text for the same topic, so a hit from the other locale would be wrong.
290
+ // JSON of the (small, fixed-shape) overrides object is a cheap fingerprint;
291
+ // undefined and {} normalize to the same string.
292
+ const textsKey = JSON.stringify(input.refErrorTexts ?? {});
293
+ const key = `${input.filePath}\u0000${input.headingLevel}\u0000${input.keyScope ? JSON.stringify(input.keyScope) : ''}\u0000${textsKey}`;
285
294
  const cached = topicRenderCache.get(key);
286
295
  if (cached &&
287
296
  cached.keyMap === input.keyMap &&
@@ -301,8 +310,9 @@ function renderTopicCached(input) {
301
310
  // Honour a caller-supplied sink as well, so anyone who passed one still
302
311
  // sees the dependency set instead of having it silently replaced.
303
312
  const dependencies = input.collectDependencies ?? new Set();
304
- // Previews only (see above), so conref'd content is always marked here.
305
- const result = renderTopicToHtml({ ...input, markConrefs: true, collectDependencies: dependencies });
313
+ // Previews only (see above), so conref'd content is always marked here and
314
+ // broken references always surface as hints rather than silent empties.
315
+ const result = renderTopicToHtml({ ...input, markConrefs: true, refErrors: true, collectDependencies: dependencies });
306
316
  if (result.error) {
307
317
  // Never cache a failure. A malformed mid-edit save is exactly the
308
318
  // transient case this path sees, and pinning it would keep serving the
package/dist/index.d.ts CHANGED
@@ -42,8 +42,10 @@ export { computeKeyrefSpacing, needsSpace } from './render/cjkSpacing';
42
42
  export { mergeProfilingAttrs, profilingChipsHtml, profilingKeysAttr } from './render/renderer';
43
43
  export { resolveConkeyref } from './editor/conkeyref';
44
44
  export { collectMapKeys, isKeyContextAvailable, keySourceMaps, qualifiedNames, qualifiedNamesMulti, resolveKeyInScope, scopeKeyIndexKey } from './editor/keySpace';
45
- export { DEFAULT_NOTE_LABELS, IMAGE_DIMENSIONS_CACHE_MAX, URL_SCHEME_RE, ZH_NOTE_LABELS, clearImageDimensionsCache, detectIndexLabel, detectNoteLabels, expandDitamapRefs, makeConrefRangeResolver, makeConrefResolver, makeFileCache, makeFileTitleResolver, makeIsInCurrentBook, readImageDimensions } from './editor/refResolvers';
45
+ export { DEFAULT_NOTE_LABELS, IMAGE_DIMENSIONS_CACHE_MAX, URL_SCHEME_RE, ZH_NOTE_LABELS, clearImageDimensionsCache, detectIndexLabel, detectNoteLabels, expandDitamapRefs, makeConrefRangeResolver, makeConrefResolver, makeFileCache, makeFileTitleResolver, makeIsInCurrentBook, makeRefErrorResolver, readImageDimensions } from './editor/refResolvers';
46
46
  export type { FileReader } from './editor/refResolvers';
47
+ export { DEFAULT_REF_ERROR_TEXTS, fillRefErrorTemplate } from './render/refErrorTexts';
48
+ export type { RefErrorTexts } from './render/refErrorTexts';
47
49
  export { buildRenderContext } from './editor/renderContext';
48
50
  export { clearAllSourceOverlays, dependsOn, noteSourceDependencies, sourceOverlaySize, sourceStamp, trackSourceReads } from './editor/sourceText';
49
51
  export { TOPIC_RENDER_CACHE_MAX_BYTES, clearTopicRenderCache, collectText, renderTopicCached, renderTopicToHtml, setTopicRenderCacheBudgetForTesting, stampFiles, topicRenderCacheBytesHeld, topicRenderCacheSize } from './editor/topicRender';
package/dist/index.js CHANGED
@@ -7,8 +7,8 @@
7
7
  // are edited here and released as a new version.
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
9
  exports.extractText = exports.createBookRoleLabeler = exports.findTopLevelIndextermsInSubtree = exports.collectIndextermChips = exports.renderElement = exports.renderDocument = exports.MAP_STANDARD_TAG_TO_BASETYPE = exports.STANDARD_TAG_TO_BASETYPE = exports.preprocessEntities = exports.parseDitamap = exports.parseDita = exports.getMapTitleText = exports.collectMapEntries = exports.pruneExcluded = exports.profileValuesOfKeys = exports.profileValuesOf = exports.profileKey = exports.profileGroups = exports.parseDitaval = exports.isValueExcluded = exports.isExcluded = exports.isEmptyFilter = exports.ditavalAction = exports.PROFILE_ATTRS = exports.renderSiteXml = exports.renderBookXml = exports.renderMapXml = exports.offsetToLineCol = exports.collectRefEntries = exports.splitRefFragment = exports.collectIds = exports.IMAGE_EXT = exports.toRelativeHref = exports.collectReferenceableFiles = exports.collectDiagnostics = exports.complete = exports.buildKeySpaceForDocument = exports.buildKeyMapForDocument = exports.decodeHrefPart = exports.clearSourceOverlay = exports.setSourceOverlay = exports.readSourceText = exports.createKeyScopeIndex = exports.getTopicScopeChains = exports.getKeyScopes = exports.getKeyDefs = exports.buildKeySpace = exports.collectDitamapFilesUpward = exports.buildTitleMap = exports.renderTopicXml = void 0;
10
- exports.collectMapSymbols = exports.topicRenderCacheSize = exports.topicRenderCacheBytesHeld = exports.stampFiles = exports.setTopicRenderCacheBudgetForTesting = exports.renderTopicToHtml = exports.renderTopicCached = exports.collectText = exports.clearTopicRenderCache = exports.TOPIC_RENDER_CACHE_MAX_BYTES = exports.trackSourceReads = exports.sourceStamp = exports.sourceOverlaySize = exports.noteSourceDependencies = exports.dependsOn = exports.clearAllSourceOverlays = exports.buildRenderContext = exports.readImageDimensions = exports.makeIsInCurrentBook = exports.makeFileTitleResolver = exports.makeFileCache = exports.makeConrefResolver = exports.makeConrefRangeResolver = exports.expandDitamapRefs = exports.detectNoteLabels = exports.detectIndexLabel = exports.clearImageDimensionsCache = exports.ZH_NOTE_LABELS = exports.URL_SCHEME_RE = exports.IMAGE_DIMENSIONS_CACHE_MAX = exports.DEFAULT_NOTE_LABELS = exports.scopeKeyIndexKey = exports.resolveKeyInScope = exports.qualifiedNamesMulti = exports.qualifiedNames = exports.keySourceMaps = exports.isKeyContextAvailable = exports.collectMapKeys = exports.resolveConkeyref = exports.profilingKeysAttr = exports.profilingChipsHtml = exports.mergeProfilingAttrs = exports.needsSpace = exports.computeKeyrefSpacing = exports.BASE_TYPE_RENDERERS = exports.lookupNamedEntity = exports.isExternalRef = exports.renderMapDocument = exports.isDitamapRef = exports.getDisplayNameInfo = void 0;
11
- exports.HOST_TOKENS = exports.stripSameDocumentFragmentPrefix = exports.getMapRefName = exports.getCompletionContext = exports.getCloseTagCompletion = exports.getAutoCloseTag = exports.getAttributesForTag = exports.findUnclosedTag = exports.findRefAttrAt = exports.findKeysAttrAt = exports.findKeyDefinitionOffset = exports.findIdAttrAt = exports.findEnclosingKeydefKeys = exports.findConrefTargetOffset = exports.collectUnknownElements = exports.collectTopicSymbols = void 0;
10
+ exports.stampFiles = exports.setTopicRenderCacheBudgetForTesting = exports.renderTopicToHtml = exports.renderTopicCached = exports.collectText = exports.clearTopicRenderCache = exports.TOPIC_RENDER_CACHE_MAX_BYTES = exports.trackSourceReads = exports.sourceStamp = exports.sourceOverlaySize = exports.noteSourceDependencies = exports.dependsOn = exports.clearAllSourceOverlays = exports.buildRenderContext = exports.fillRefErrorTemplate = exports.DEFAULT_REF_ERROR_TEXTS = exports.readImageDimensions = exports.makeRefErrorResolver = exports.makeIsInCurrentBook = exports.makeFileTitleResolver = exports.makeFileCache = exports.makeConrefResolver = exports.makeConrefRangeResolver = exports.expandDitamapRefs = exports.detectNoteLabels = exports.detectIndexLabel = exports.clearImageDimensionsCache = exports.ZH_NOTE_LABELS = exports.URL_SCHEME_RE = exports.IMAGE_DIMENSIONS_CACHE_MAX = exports.DEFAULT_NOTE_LABELS = exports.scopeKeyIndexKey = exports.resolveKeyInScope = exports.qualifiedNamesMulti = exports.qualifiedNames = exports.keySourceMaps = exports.isKeyContextAvailable = exports.collectMapKeys = exports.resolveConkeyref = exports.profilingKeysAttr = exports.profilingChipsHtml = exports.mergeProfilingAttrs = exports.needsSpace = exports.computeKeyrefSpacing = exports.BASE_TYPE_RENDERERS = exports.lookupNamedEntity = exports.isExternalRef = exports.renderMapDocument = exports.isDitamapRef = exports.getDisplayNameInfo = void 0;
11
+ exports.HOST_TOKENS = exports.stripSameDocumentFragmentPrefix = exports.getMapRefName = exports.getCompletionContext = exports.getCloseTagCompletion = exports.getAutoCloseTag = exports.getAttributesForTag = exports.findUnclosedTag = exports.findRefAttrAt = exports.findKeysAttrAt = exports.findKeyDefinitionOffset = exports.findIdAttrAt = exports.findEnclosingKeydefKeys = exports.findConrefTargetOffset = exports.collectUnknownElements = exports.collectTopicSymbols = exports.collectMapSymbols = exports.topicRenderCacheSize = exports.topicRenderCacheBytesHeld = void 0;
12
12
  var topicRender_1 = require("./editor/topicRender");
13
13
  Object.defineProperty(exports, "renderTopicXml", { enumerable: true, get: function () { return topicRender_1.renderTopicXml; } });
14
14
  Object.defineProperty(exports, "buildTitleMap", { enumerable: true, get: function () { return topicRender_1.buildTitleMap; } });
@@ -128,7 +128,11 @@ Object.defineProperty(exports, "makeConrefResolver", { enumerable: true, get: fu
128
128
  Object.defineProperty(exports, "makeFileCache", { enumerable: true, get: function () { return refResolvers_2.makeFileCache; } });
129
129
  Object.defineProperty(exports, "makeFileTitleResolver", { enumerable: true, get: function () { return refResolvers_2.makeFileTitleResolver; } });
130
130
  Object.defineProperty(exports, "makeIsInCurrentBook", { enumerable: true, get: function () { return refResolvers_2.makeIsInCurrentBook; } });
131
+ Object.defineProperty(exports, "makeRefErrorResolver", { enumerable: true, get: function () { return refResolvers_2.makeRefErrorResolver; } });
131
132
  Object.defineProperty(exports, "readImageDimensions", { enumerable: true, get: function () { return refResolvers_2.readImageDimensions; } });
133
+ var refErrorTexts_1 = require("./render/refErrorTexts");
134
+ Object.defineProperty(exports, "DEFAULT_REF_ERROR_TEXTS", { enumerable: true, get: function () { return refErrorTexts_1.DEFAULT_REF_ERROR_TEXTS; } });
135
+ Object.defineProperty(exports, "fillRefErrorTemplate", { enumerable: true, get: function () { return refErrorTexts_1.fillRefErrorTemplate; } });
132
136
  var renderContext_1 = require("./editor/renderContext");
133
137
  Object.defineProperty(exports, "buildRenderContext", { enumerable: true, get: function () { return renderContext_1.buildRenderContext; } });
134
138
  var sourceText_2 = require("./editor/sourceText");
@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.BASE_TYPE_RENDERERS = void 0;
4
4
  exports.collectIndextermChips = collectIndextermChips;
5
5
  exports.findTopLevelIndextermsInSubtree = findTopLevelIndextermsInSubtree;
6
+ const refErrorTexts_1 = require("./refErrorTexts");
7
+ const refTargets_1 = require("./refTargets");
6
8
  // parentBaseType only reflects the immediate ancestor (entry sits under row,
7
9
  // not thead), so header status is carried by an explicit ctx flag set when
8
10
  // entering thead/sthead and cleared when entering tbody.
@@ -813,6 +815,28 @@ exports.BASE_TYPE_RENDERERS = {
813
815
  return '';
814
816
  return `<span class="xref unresolved-keyref" title="Unresolved key: ${escapeAttr(keyref)}">[${escapeAttr(keyref)}]</span>`;
815
817
  }
818
+ // An EMPTY xref whose local target is broken (host-diagnosed, see
819
+ // RenderContext.refError): the title/href fallback below would render
820
+ // the raw href in a link-shaped hint that reads as if the reference
821
+ // worked -- the silent failure this marker exists to surface. Keep the
822
+ // arrow convention of the xref-external hint, but in the error colour
823
+ // with a dashed underline and the reason appended. An xref WITH author
824
+ // text keeps it (content wins, same rule as keyref); scope=external/peer
825
+ // references are not local documents and are never diagnosed.
826
+ if (!hasContentChildren(node) && ctx.refError) {
827
+ const scope = getAttr(node, 'scope');
828
+ // An xref whose @format names a non-DITA target (html, pdf, ...) does
829
+ // not point at a DITA id: its fragment is the target format's own
830
+ // (#page=3, #section), so it is never diagnosed.
831
+ if (scope !== 'external' && scope !== 'peer' && (0, refTargets_1.isDitaFormat)(getAttr(node, 'format'))) {
832
+ const reason = ctx.refError(href);
833
+ if (reason !== undefined) {
834
+ const texts = { ...refErrorTexts_1.DEFAULT_REF_ERROR_TEXTS, ...ctx.refErrorTexts };
835
+ const text = (0, refErrorTexts_1.fillRefErrorTemplate)(texts.xref, href, reason);
836
+ return `<span class="xref-broken" title="${escapeAttr(href)}">${escapeAttr(text)}</span>`;
837
+ }
838
+ }
839
+ }
816
840
  let content;
817
841
  if (hasContentChildren(node)) {
818
842
  content = renderChildren(node, ctx);
@@ -0,0 +1,27 @@
1
+ export interface RefErrorTexts {
2
+ /**
3
+ * Placeholder chip replacing a conref that pulled nothing.
4
+ * {0} = the reason refError returned.
5
+ */
6
+ content: string;
7
+ /**
8
+ * Marker replacing an EMPTY xref whose target is broken.
9
+ * {0} = the raw href, {1} = the reason refError returned.
10
+ */
11
+ xref: string;
12
+ /** Reason (conkeyref only): the key is not defined, or has no resource target. */
13
+ missingKey: string;
14
+ /** Reason: the referenced file is not in the repository closure. */
15
+ missingFile: string;
16
+ /** Reason: the file exists but is not well-formed XML. */
17
+ parseError: string;
18
+ /** Reason: the file parses but #topicId/elementId names no id in it. */
19
+ missingId: string;
20
+ }
21
+ export declare const DEFAULT_REF_ERROR_TEXTS: RefErrorTexts;
22
+ /**
23
+ * Fills {0}, {1}, ... in a template. split/join rather than
24
+ * String.replace: the substituted values are arbitrary reference text
25
+ * (an href, a reason) and must not be read for $-patterns.
26
+ */
27
+ export declare function fillRefErrorTemplate(template: string, ...values: string[]): string;
@@ -0,0 +1,43 @@
1
+ "use strict";
2
+ // Wording for the broken-reference hints (RenderContext.refError).
3
+ //
4
+ // A LEAF module: no imports, so both the renderer (render/renderer.ts,
5
+ // render/baseTypeMap.ts) and the editor-layer resolver factory
6
+ // (editor/refResolvers.ts) can read it without a cycle -- the same reason
7
+ // FALLBACK_NOTE_LABELS is duplicated in baseTypeMap rather than imported
8
+ // from the editor layer, solved here by putting the shared strings below
9
+ // both instead.
10
+ //
11
+ // The renderer only PRESENTS: it asks RenderContext.refError whether a
12
+ // reference is broken and composes the answer with the templates below.
13
+ // The diagnosis itself is the host's (the callback), and so is the
14
+ // localization -- a host fills these from its own string catalog (the VS
15
+ // Code extension does, via vscode.l10n.t); the defaults here are English.
16
+ //
17
+ // Templates use {0}/{1} placeholders rather than concatenation so a
18
+ // locale controls the whole shape, punctuation included: zh-cn wraps the
19
+ // reason in full-width parentheses(…)where English uses (…) .
20
+ Object.defineProperty(exports, "__esModule", { value: true });
21
+ exports.DEFAULT_REF_ERROR_TEXTS = void 0;
22
+ exports.fillRefErrorTemplate = fillRefErrorTemplate;
23
+ exports.DEFAULT_REF_ERROR_TEXTS = {
24
+ content: 'Referenced content could not be resolved ({0})',
25
+ xref: '→ {0} ({1})',
26
+ missingKey: 'key is not defined or has no target',
27
+ missingFile: 'target file does not exist',
28
+ parseError: 'target file cannot be parsed as XML',
29
+ missingId: 'target ID does not exist',
30
+ };
31
+ /**
32
+ * Fills {0}, {1}, ... in a template. split/join rather than
33
+ * String.replace: the substituted values are arbitrary reference text
34
+ * (an href, a reason) and must not be read for $-patterns.
35
+ */
36
+ function fillRefErrorTemplate(template, ...values) {
37
+ let out = template;
38
+ for (let i = 0; i < values.length; i++) {
39
+ out = out.split(`{${i}}`).join(values[i]);
40
+ }
41
+ return out;
42
+ }
43
+ //# sourceMappingURL=refErrorTexts.js.map
@@ -0,0 +1,12 @@
1
+ /** A URL scheme (https:, mailto:, ...) -- and, by the same shape, a Windows
2
+ * drive letter (C:\...), which is no DITA-relative path either. */
3
+ export declare const URL_SCHEME_RE: RegExp;
4
+ /**
5
+ * True for a file part that is not a local DITA document, so a hint must
6
+ * never probe it: a URL, an absolute path, or a web document (.html, .htm,
7
+ * .pdf), whose #fragment is the format's own (#page=3, #section) rather than
8
+ * a DITA id. Pass the part BEFORE any '#'.
9
+ */
10
+ export declare function isNonDitaTarget(filePart: string): boolean;
11
+ /** True when an @format value names a DITA target (absent means DITA). */
12
+ export declare function isDitaFormat(format: string | undefined): boolean;
@@ -0,0 +1,31 @@
1
+ "use strict";
2
+ // What a reference can point at, as far as the broken-reference hints are
3
+ // concerned: is this a target the hints may probe at all?
4
+ //
5
+ // A LEAF module (no imports, not even 'path'), like refErrorTexts.ts, so the
6
+ // renderer (baseTypeMap), the resolver factory (editor/refResolvers) and the
7
+ // conkeyref diagnosis (editor/conkeyref) can share ONE rule without a cycle
8
+ // or a dependency on the filesystem layer. Three call sites used to spell the
9
+ // rule out separately; a fourth extension (or a new scheme) now changes one
10
+ // place.
11
+ Object.defineProperty(exports, "__esModule", { value: true });
12
+ exports.URL_SCHEME_RE = void 0;
13
+ exports.isNonDitaTarget = isNonDitaTarget;
14
+ exports.isDitaFormat = isDitaFormat;
15
+ /** A URL scheme (https:, mailto:, ...) -- and, by the same shape, a Windows
16
+ * drive letter (C:\...), which is no DITA-relative path either. */
17
+ exports.URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
18
+ /**
19
+ * True for a file part that is not a local DITA document, so a hint must
20
+ * never probe it: a URL, an absolute path, or a web document (.html, .htm,
21
+ * .pdf), whose #fragment is the format's own (#page=3, #section) rather than
22
+ * a DITA id. Pass the part BEFORE any '#'.
23
+ */
24
+ function isNonDitaTarget(filePart) {
25
+ return exports.URL_SCHEME_RE.test(filePart) || /^[\\/]/.test(filePart) || /\.(html?|pdf)$/i.test(filePart);
26
+ }
27
+ /** True when an @format value names a DITA target (absent means DITA). */
28
+ function isDitaFormat(format) {
29
+ return !format || format === 'dita' || format === 'ditamap';
30
+ }
31
+ //# sourceMappingURL=refTargets.js.map