@dita-viewer/core 0.2.0 → 0.2.2
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.
- package/LICENSE +21 -21
- package/README.md +90 -58
- package/dist/editor/renderContext.d.ts +7 -0
- package/dist/editor/renderContext.js +24 -0
- package/dist/editor/topicRender.d.ts +9 -0
- package/dist/editor/topicRender.js +4 -2
- package/dist/index.js +3 -3
- package/dist/language/ditaLanguageUtils.js +2 -0
- package/dist/profiling.d.ts +9 -3
- package/dist/profiling.js +12 -6
- package/dist/render/baseTypeMap.js +28 -2
- package/dist/render/mapTypeMap.js +23 -23
- package/dist/render/renderer.d.ts +24 -0
- package/dist/render/renderer.js +36 -9
- package/dist-esm/bookRender.js +145 -0
- package/dist-esm/completion.js +142 -0
- package/dist-esm/completionData.js +155 -0
- package/dist-esm/diagnostics.js +378 -0
- package/dist-esm/editor/conkeyref.js +104 -0
- package/dist-esm/editor/keySpace.js +201 -0
- package/dist-esm/editor/refResolvers.js +633 -0
- package/dist-esm/editor/renderContext.js +138 -0
- package/dist-esm/editor/sourceText.js +142 -0
- package/dist-esm/editor/topicRender.js +328 -0
- package/dist-esm/index.js +66 -0
- package/dist-esm/keyMapForDocument.js +23 -0
- package/dist-esm/language/ditaLanguageUtils.js +659 -0
- package/dist-esm/language/referenceableFiles.js +108 -0
- package/dist-esm/mapRender.js +24 -0
- package/dist-esm/package.json +1 -0
- package/dist-esm/parser/ditaParser.js +409 -0
- package/dist-esm/parser/domTypes.js +1 -0
- package/dist-esm/parser/mapTagMap.js +77 -0
- package/dist-esm/parser/namedEntities.js +321 -0
- package/dist-esm/parser/standardTagMap.js +393 -0
- package/dist-esm/profiling.js +224 -0
- package/dist-esm/render/baseTypeMap.js +1057 -0
- package/dist-esm/render/cjkSpacing.js +94 -0
- package/dist-esm/render/mapTypeMap.js +568 -0
- package/dist-esm/render/renderer.js +519 -0
- package/dist-esm/siteRender.js +261 -0
- package/package.json +55 -53
- package/styles/TOKENS.md +59 -38
- package/styles/dita-content.css +1171 -1157
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
// Shared render-context factory (P2).
|
|
2
|
+
//
|
|
3
|
+
// The three DITA render paths -- renderTopicXml (book / site / map preview),
|
|
4
|
+
// DitaViewerProvider.renderTopicContentUntracked (single-topic custom editor)
|
|
5
|
+
// and ditaDiffProvider.computeDiff (the Git compare panel) -- each used to
|
|
6
|
+
// hand-assemble the same conref / keyref / title / image resolvers into a
|
|
7
|
+
// RenderContext. Duplicating the wiring meant that adding a resolver (the
|
|
8
|
+
// upcoming conkeyref, P3) in one path would silently leave the other two
|
|
9
|
+
// behind. Centralising it here means the key resolvers are wired once.
|
|
10
|
+
//
|
|
11
|
+
// Pure module: no vscode import. `asWebviewUri` and the document directory
|
|
12
|
+
// are passed in by the caller (those are the only genuinely per-path bits),
|
|
13
|
+
// so the whole factory is unit-testable in plain mocha.
|
|
14
|
+
//
|
|
15
|
+
// What legitimately differs per path stays as input flags, so wiring the
|
|
16
|
+
// factory in is behaviour-preserving:
|
|
17
|
+
// - includeIndexLabel: preview and book set indexLabel, the diff view does
|
|
18
|
+
// not (it never surfaces indexterm chips). Kept as a flag to preserve
|
|
19
|
+
// that byte-for-byte.
|
|
20
|
+
// - collectDependencies / bookMembers: only the book/site path uses them.
|
|
21
|
+
// collectDependencies also folds image reads into the dependency set.
|
|
22
|
+
// - suppressIndexterm: only the export path sets it.
|
|
23
|
+
import { resolve, relative, isAbsolute } from 'path';
|
|
24
|
+
import { makeFileCache, makeConrefResolver, makeConrefRangeResolver, makeFileTitleResolver, makeIsInCurrentBook, detectNoteLabels, detectIndexLabel, readImageDimensions, decodeHrefPart, URL_SCHEME_RE, } from './refResolvers';
|
|
25
|
+
import { getKeyDefs } from './keySpace';
|
|
26
|
+
import { resolveConkeyref } from './conkeyref';
|
|
27
|
+
export function buildRenderContext(input) {
|
|
28
|
+
const { docDir, ownRoot, titleMap, keyMap, asWebviewUri, headingLevel, uiLanguage } = input;
|
|
29
|
+
// One cache shared by all three resolvers. They routinely load the same
|
|
30
|
+
// conref/title target; sharing avoids re-parsing it and gives a single
|
|
31
|
+
// place to read back the complete set of files this render touched.
|
|
32
|
+
const fileCache = makeFileCache(docDir);
|
|
33
|
+
const conrefResolver = makeConrefResolver(docDir, ownRoot, fileCache);
|
|
34
|
+
const conrefRangeResolver = makeConrefRangeResolver(docDir, ownRoot, fileCache);
|
|
35
|
+
const fileTitleResolver = makeFileTitleResolver(docDir, fileCache);
|
|
36
|
+
const ctx = {
|
|
37
|
+
headingLevel,
|
|
38
|
+
asWebviewUri,
|
|
39
|
+
documentDir: docDir,
|
|
40
|
+
// Local id match first, then cross-file ("file.dita#topicId" or "file.dita").
|
|
41
|
+
resolveTitle: (id) => titleMap.get(id) || fileTitleResolver(id),
|
|
42
|
+
resolveKey: (key) => keyMap.get(key),
|
|
43
|
+
resolveConref: (conref) => conrefResolver(conref),
|
|
44
|
+
resolveConrefRange: (conref, conrefend) => conrefRangeResolver(conref, conrefend),
|
|
45
|
+
noteLabels: detectNoteLabels(ownRoot, uiLanguage),
|
|
46
|
+
suppressIndexterm: input.suppressIndexterm,
|
|
47
|
+
getImageDimensions: (relPath) => {
|
|
48
|
+
try {
|
|
49
|
+
const absPath = resolve(docDir, decodeHrefPart(relPath));
|
|
50
|
+
// An image's dimensions are emitted as width/height attributes, so
|
|
51
|
+
// the file is a genuine dependency of the rendered HTML and has to be
|
|
52
|
+
// recorded alongside the conref/title targets (only when the caller
|
|
53
|
+
// passes a sink -- the preview and diff paths do not).
|
|
54
|
+
input.collectDependencies?.add(absPath);
|
|
55
|
+
return readImageDimensions(absPath);
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
return undefined;
|
|
59
|
+
}
|
|
60
|
+
},
|
|
61
|
+
};
|
|
62
|
+
if (input.markConrefs && input.docFile) {
|
|
63
|
+
const docFile = input.docFile;
|
|
64
|
+
// origins only holds elements resolved from another file or through a
|
|
65
|
+
// chain; a same-document target has none, and lives in docFile.
|
|
66
|
+
ctx.conrefSource = (target) => fileCache.originOf(target)?.file ?? docFile;
|
|
67
|
+
}
|
|
68
|
+
if (input.includeIndexLabel)
|
|
69
|
+
ctx.indexLabel = detectIndexLabel(ownRoot, uiLanguage);
|
|
70
|
+
if (input.bookMembers)
|
|
71
|
+
ctx.isInCurrentBook = makeIsInCurrentBook(docDir, input.bookMembers);
|
|
72
|
+
if (input.clickableExternalXrefs)
|
|
73
|
+
ctx.clickableExternalXrefs = true;
|
|
74
|
+
// conkeyref rides on the same file cache: a key's href resolves against the
|
|
75
|
+
// map that defined it (baseDir), not the topic being rendered, so it needs
|
|
76
|
+
// the absolute-path loader rather than the docDir-relative conref resolver.
|
|
77
|
+
// Discovered from keyMap by identity unless the caller passed defs directly.
|
|
78
|
+
let lastLoaded;
|
|
79
|
+
const keyDefs = input.keyDefs ?? getKeyDefs(keyMap);
|
|
80
|
+
if (keyDefs && keyDefs.size > 0) {
|
|
81
|
+
// A keyref on a link-shaped element (topic/xref) resolves to the key's
|
|
82
|
+
// resource target as its effective href. The keydef's href is relative
|
|
83
|
+
// to the map that defined it, but every href the renderer consumes
|
|
84
|
+
// (isInCurrentBook, resolveTitle, the preview's own open-by-href) is
|
|
85
|
+
// relative to the DOCUMENT's folder -- so rebase here, preserving any
|
|
86
|
+
// element-id fragment, and hand through the shapes that are not
|
|
87
|
+
// filesystem paths (URL schemes, absolute paths) untouched.
|
|
88
|
+
ctx.resolveKeyHref = (key) => {
|
|
89
|
+
const def = keyDefs.get(key);
|
|
90
|
+
if (!def?.href)
|
|
91
|
+
return undefined;
|
|
92
|
+
const raw = def.href;
|
|
93
|
+
if (URL_SCHEME_RE.test(raw) || isAbsolute(raw))
|
|
94
|
+
return raw;
|
|
95
|
+
const hashIdx = raw.indexOf('#');
|
|
96
|
+
const pathPart = hashIdx >= 0 ? raw.slice(0, hashIdx) : raw;
|
|
97
|
+
const fragment = hashIdx >= 0 ? raw.slice(hashIdx) : '';
|
|
98
|
+
if (!pathPart)
|
|
99
|
+
return fragment || undefined;
|
|
100
|
+
const abs = resolve(def.baseDir, decodeHrefPart(pathPart));
|
|
101
|
+
return relative(docDir, abs).replace(/\\/g, '/') + fragment;
|
|
102
|
+
};
|
|
103
|
+
const loadTopic = (baseDir, href) => {
|
|
104
|
+
const absPath = resolve(baseDir, decodeHrefPart(href.split('#')[0]));
|
|
105
|
+
// A conkeyref target is a real dependency of the rendered HTML, exactly
|
|
106
|
+
// like a conref target; record it when the caller tracks dependencies.
|
|
107
|
+
input.collectDependencies?.add(absPath);
|
|
108
|
+
return fileCache.loadAbsPath(absPath);
|
|
109
|
+
};
|
|
110
|
+
ctx.resolveConkeyref = (conkeyref) => {
|
|
111
|
+
const el = resolveConkeyref(conkeyref, keyDefs, (baseDir, href) => {
|
|
112
|
+
const absPath = resolve(baseDir, decodeHrefPart(href.split('#')[0]));
|
|
113
|
+
const root = loadTopic(baseDir, href);
|
|
114
|
+
if (root)
|
|
115
|
+
lastLoaded = { file: absPath, root };
|
|
116
|
+
return root;
|
|
117
|
+
});
|
|
118
|
+
if (el && lastLoaded)
|
|
119
|
+
fileCache.noteOrigin(el, lastLoaded);
|
|
120
|
+
return el;
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
// One hop further along a reference chain, resolved relative to the file
|
|
124
|
+
// that holds `from`. conkeyref wins over conref when it resolves, the same
|
|
125
|
+
// rule as the first hop (an unresolvable conkeyref falls back to conref).
|
|
126
|
+
ctx.resolveChainHop = (from) => {
|
|
127
|
+
const conkeyref = from.attributes?.conkeyref;
|
|
128
|
+
if (conkeyref && ctx.resolveConkeyref) {
|
|
129
|
+
lastLoaded = undefined;
|
|
130
|
+
const viaKey = ctx.resolveConkeyref(conkeyref);
|
|
131
|
+
if (viaKey)
|
|
132
|
+
return viaKey;
|
|
133
|
+
}
|
|
134
|
+
const conref = from.attributes?.conref;
|
|
135
|
+
return conref ? conrefResolver(conref, from) : undefined;
|
|
136
|
+
};
|
|
137
|
+
return { ctx, touchedFiles: () => fileCache.touchedFiles() };
|
|
138
|
+
}
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How the extension reads and fingerprints DITA source files.
|
|
3
|
+
*
|
|
4
|
+
* Previews are built from more than the document on screen -- conref targets,
|
|
5
|
+
* mapref'd maps, keydef maps, the topics of a book -- and those used to be
|
|
6
|
+
* read from disk, so text that was typed into an editor tab but not saved
|
|
7
|
+
* did not show. The overlay below is the fix: a registry of the unsaved text
|
|
8
|
+
* of open documents. Every read of a DITA source goes through readSourceText
|
|
9
|
+
* (the unsaved text if there is any, otherwise the disk), and every cache
|
|
10
|
+
* fingerprint through sourceStamp (which changes when either does).
|
|
11
|
+
*
|
|
12
|
+
* Pure of the vscode module, so the rules here can be unit-tested; the code
|
|
13
|
+
* that feeds it from editor events is in sourceOverlaySync.ts.
|
|
14
|
+
*/
|
|
15
|
+
import { readFileSync, statSync } from 'fs';
|
|
16
|
+
import { normalize } from 'path';
|
|
17
|
+
const overlay = new Map();
|
|
18
|
+
/**
|
|
19
|
+
* One counter for every overlay change to every file, never reset. A stamp
|
|
20
|
+
* built from it cannot collide with an earlier one: document.version, the
|
|
21
|
+
* obvious alternative, restarts at 1 whenever a document is closed and
|
|
22
|
+
* reopened, so "discard changes, reopen, type something else" could land on
|
|
23
|
+
* a version number a cache entry was already built for.
|
|
24
|
+
*/
|
|
25
|
+
let revision = 0;
|
|
26
|
+
/**
|
|
27
|
+
* Same file however the path is spelled: `..` segments, case on Windows, and
|
|
28
|
+
* `/` vs `\` -- normalize() only resolves the former two and, on win32,
|
|
29
|
+
* rewrites `/` to `\`, so a caller (or a test) that builds a path with `/`
|
|
30
|
+
* throughout gets a different key than the disk path unless both are folded
|
|
31
|
+
* to one separator here.
|
|
32
|
+
*/
|
|
33
|
+
function key(filePath) {
|
|
34
|
+
const n = normalize(filePath).replace(/\\/g, '/');
|
|
35
|
+
return process.platform === 'win32' ? n.toLowerCase() : n;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Records `text` as the current unsaved content of a file. A no-op when it
|
|
39
|
+
* already is: editor events fire for changes that do not alter the text (a
|
|
40
|
+
* re-sync on open, a dirty-flag flip), and each real change here invalidates
|
|
41
|
+
* every cache built from the file.
|
|
42
|
+
*/
|
|
43
|
+
export function setSourceOverlay(filePath, text) {
|
|
44
|
+
const k = key(filePath);
|
|
45
|
+
const existing = overlay.get(k);
|
|
46
|
+
if (existing && existing.text === text)
|
|
47
|
+
return;
|
|
48
|
+
overlay.set(k, { text, rev: ++revision });
|
|
49
|
+
}
|
|
50
|
+
/** The file is saved, reverted or closed: the disk is the truth again. */
|
|
51
|
+
export function clearSourceOverlay(filePath) {
|
|
52
|
+
overlay.delete(key(filePath));
|
|
53
|
+
}
|
|
54
|
+
export function clearAllSourceOverlays() {
|
|
55
|
+
overlay.clear();
|
|
56
|
+
}
|
|
57
|
+
/** How many files currently have unsaved text -- test hook. */
|
|
58
|
+
export function sourceOverlaySize() {
|
|
59
|
+
return overlay.size;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* The text of a DITA source file as the author currently has it: unsaved
|
|
63
|
+
* editor text when there is some, the file on disk otherwise. Throws exactly
|
|
64
|
+
* as readFileSync does for an unreadable file, so callers keep their existing
|
|
65
|
+
* error handling. The one-value encoding parameter is what expandDitamapRefs'
|
|
66
|
+
* FileReader type asks for.
|
|
67
|
+
*/
|
|
68
|
+
export function readSourceText(filePath, encoding = 'utf-8') {
|
|
69
|
+
const k = key(filePath);
|
|
70
|
+
recorder?.add(k);
|
|
71
|
+
const entry = overlay.get(k);
|
|
72
|
+
return entry ? entry.text : readFileSync(filePath, encoding);
|
|
73
|
+
}
|
|
74
|
+
// ── Which sources a render read ──
|
|
75
|
+
//
|
|
76
|
+
// A preview panel has to decide, for an edit made in some other document,
|
|
77
|
+
// whether that edit can change what it shows. The answer is exactly "did my
|
|
78
|
+
// last render read that file", which the readers above can report as they go.
|
|
79
|
+
let recorder;
|
|
80
|
+
/**
|
|
81
|
+
* Runs `fn` and returns its result along with every source file read through
|
|
82
|
+
* readSourceText while it ran (as normalized keys, for dependsOn). Nests: an
|
|
83
|
+
* inner call gets its own files, and they are also added to the outer one.
|
|
84
|
+
* Anything that answers from a cache instead of reading must say what the
|
|
85
|
+
* cached answer was built from -- see noteSourceDependencies.
|
|
86
|
+
*/
|
|
87
|
+
export function trackSourceReads(fn) {
|
|
88
|
+
const outer = recorder;
|
|
89
|
+
const mine = new Set();
|
|
90
|
+
recorder = mine;
|
|
91
|
+
try {
|
|
92
|
+
return { result: fn(), files: mine };
|
|
93
|
+
}
|
|
94
|
+
finally {
|
|
95
|
+
recorder = outer;
|
|
96
|
+
if (outer)
|
|
97
|
+
for (const f of mine)
|
|
98
|
+
outer.add(f);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* For a cache hit: reading nothing does not mean depending on nothing. The
|
|
103
|
+
* cache entry knows the files it was built from, and reports them here so an
|
|
104
|
+
* enclosing trackSourceReads sees the same set on the second pass as on the
|
|
105
|
+
* first. A no-op outside a tracker.
|
|
106
|
+
*/
|
|
107
|
+
export function noteSourceDependencies(filePaths) {
|
|
108
|
+
if (!recorder)
|
|
109
|
+
return;
|
|
110
|
+
for (const p of filePaths)
|
|
111
|
+
recorder.add(key(p));
|
|
112
|
+
}
|
|
113
|
+
/** Whether a set returned by trackSourceReads contains this file, however its path is spelled. */
|
|
114
|
+
export function dependsOn(files, filePath) {
|
|
115
|
+
return files.has(key(filePath));
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* A fingerprint of one file, comparable by string equality: two calls return
|
|
119
|
+
* the same string exactly when nothing that matters to a cached render
|
|
120
|
+
* derived from the file changed in between.
|
|
121
|
+
*
|
|
122
|
+
* `dirty:<rev>` while the file has unsaved text; `<mtimeMs>:<size>` on disk.
|
|
123
|
+
* mtime alone is not enough -- a restored timestamp (git checkout, a copy
|
|
124
|
+
* tool, a coarse-grained file system) can leave it equal for a file whose
|
|
125
|
+
* content is different, and size catches most of those at the cost of one
|
|
126
|
+
* field of the stat that is already being made. A file that cannot be
|
|
127
|
+
* statted is "?", so deleting a dependency invalidates exactly as modifying
|
|
128
|
+
* it does, and creating one that was missing turns "?" into a real stamp --
|
|
129
|
+
* the other half of the same requirement.
|
|
130
|
+
*/
|
|
131
|
+
export function sourceStamp(filePath) {
|
|
132
|
+
const entry = overlay.get(key(filePath));
|
|
133
|
+
if (entry)
|
|
134
|
+
return `dirty:${entry.rev}`;
|
|
135
|
+
try {
|
|
136
|
+
const st = statSync(filePath);
|
|
137
|
+
return `${st.mtimeMs}:${st.size}`;
|
|
138
|
+
}
|
|
139
|
+
catch {
|
|
140
|
+
return '?';
|
|
141
|
+
}
|
|
142
|
+
}
|
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
// Topic rendering pipeline: text/title extraction, interfaces, parse-and-render
|
|
2
|
+
// functions, and the LRU render cache that book mode uses to skip re-rendering
|
|
3
|
+
// unchanged topics. Moved verbatim from ditaRenderUtils.ts (P5 pure refactor);
|
|
4
|
+
// imports its dependencies from sibling modules so no cycle through the barrel.
|
|
5
|
+
import { existsSync, readdirSync } from 'fs';
|
|
6
|
+
import { dirname, join } from 'path';
|
|
7
|
+
import { parseDita, preprocessEntities } from '../parser/ditaParser';
|
|
8
|
+
import { renderDocument } from '../render/renderer';
|
|
9
|
+
import { buildRenderContext } from './renderContext';
|
|
10
|
+
import { sourceStamp, readSourceText, noteSourceDependencies } from './sourceText';
|
|
11
|
+
// ── Text extraction ──
|
|
12
|
+
export function collectText(node) {
|
|
13
|
+
if (node.type === 'text')
|
|
14
|
+
return node.text || '';
|
|
15
|
+
return (node.children || []).map(collectText).join('');
|
|
16
|
+
}
|
|
17
|
+
// ── Title map (id → title text for xref) ──
|
|
18
|
+
export function buildTitleMap(root) {
|
|
19
|
+
const map = new Map();
|
|
20
|
+
function walk(node) {
|
|
21
|
+
if (node.type === 'element') {
|
|
22
|
+
const id = node.attributes?.id;
|
|
23
|
+
if (id) {
|
|
24
|
+
const titleChild = (node.children || []).find((c) => c.type === 'element' && c.baseType === 'topic/title');
|
|
25
|
+
if (titleChild) {
|
|
26
|
+
map.set(id, collectText(titleChild));
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
for (const child of node.children || [])
|
|
30
|
+
walk(child);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
walk(root);
|
|
34
|
+
return map;
|
|
35
|
+
}
|
|
36
|
+
export function renderTopicXml(input) {
|
|
37
|
+
const { xml, docDir, keyMap, asWebviewUri, headingLevel, uiLanguage, suppressIndexterm, collectDependencies, bookMembers, clickableExternalXrefs, docFile, markConrefs } = input;
|
|
38
|
+
try {
|
|
39
|
+
const preprocessedXml = preprocessEntities(xml);
|
|
40
|
+
const ditaDoc = parseDita(preprocessedXml);
|
|
41
|
+
const titleMap = buildTitleMap(ditaDoc.root);
|
|
42
|
+
// Resolvers, note/index labels and image dimensions are assembled by the
|
|
43
|
+
// shared buildRenderContext factory (renderContext.ts) so this path, the
|
|
44
|
+
// single-topic preview and the diff panel wire them identically. The book
|
|
45
|
+
// extras (isInCurrentBook, collectDependencies) and indexLabel are on here.
|
|
46
|
+
const { ctx, touchedFiles } = buildRenderContext({
|
|
47
|
+
docDir,
|
|
48
|
+
ownRoot: ditaDoc.root,
|
|
49
|
+
titleMap,
|
|
50
|
+
keyMap,
|
|
51
|
+
asWebviewUri,
|
|
52
|
+
headingLevel,
|
|
53
|
+
uiLanguage,
|
|
54
|
+
includeIndexLabel: true,
|
|
55
|
+
suppressIndexterm,
|
|
56
|
+
bookMembers,
|
|
57
|
+
clickableExternalXrefs,
|
|
58
|
+
collectDependencies,
|
|
59
|
+
docFile,
|
|
60
|
+
markConrefs,
|
|
61
|
+
});
|
|
62
|
+
const html = renderDocument(ditaDoc.root, ctx);
|
|
63
|
+
if (collectDependencies) {
|
|
64
|
+
for (const touched of touchedFiles())
|
|
65
|
+
collectDependencies.add(touched);
|
|
66
|
+
}
|
|
67
|
+
const titleNode = (ditaDoc.root.children || []).find((c) => c.type === 'element' && c.baseType === 'topic/title');
|
|
68
|
+
const title = titleNode ? collectText(titleNode) : undefined;
|
|
69
|
+
return { doc: ditaDoc, html, title };
|
|
70
|
+
}
|
|
71
|
+
catch (err) {
|
|
72
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
73
|
+
return { html: '', error: `Error rendering topic: ${message}` };
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
export function renderTopicToHtml(input) {
|
|
77
|
+
const { filePath, keyMap, asWebviewUri, headingLevel, uiLanguage, suppressIndexterm, collectDependencies, bookMembers, clickableExternalXrefs, markConrefs } = input;
|
|
78
|
+
try {
|
|
79
|
+
if (!existsSync(filePath)) {
|
|
80
|
+
return { html: '', error: `File not found: ${filePath}` };
|
|
81
|
+
}
|
|
82
|
+
// The topic's own file is a dependency of its own render even though it
|
|
83
|
+
// is read here rather than through the shared file cache.
|
|
84
|
+
collectDependencies?.add(filePath);
|
|
85
|
+
const rawXml = readSourceText(filePath, 'utf-8');
|
|
86
|
+
const result = renderTopicXml({
|
|
87
|
+
xml: rawXml,
|
|
88
|
+
docDir: dirname(filePath),
|
|
89
|
+
keyMap,
|
|
90
|
+
asWebviewUri,
|
|
91
|
+
headingLevel,
|
|
92
|
+
uiLanguage,
|
|
93
|
+
suppressIndexterm,
|
|
94
|
+
collectDependencies,
|
|
95
|
+
bookMembers,
|
|
96
|
+
clickableExternalXrefs,
|
|
97
|
+
docFile: filePath,
|
|
98
|
+
markConrefs,
|
|
99
|
+
});
|
|
100
|
+
return { html: result.html, title: result.title, error: result.error };
|
|
101
|
+
}
|
|
102
|
+
catch (err) {
|
|
103
|
+
const message = err instanceof Error ? err.message : String(err);
|
|
104
|
+
return { html: '', error: `Error rendering ${filePath}: ${message}` };
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
// ── Topic render cache (book mode) ──
|
|
108
|
+
/**
|
|
109
|
+
* Fingerprint of a set of files, used to decide whether a cached result
|
|
110
|
+
* derived from them is still valid: one sourceStamp per file (sourceText.ts
|
|
111
|
+
* has the rules, including how a missing file and a changed size count),
|
|
112
|
+
* joined in order.
|
|
113
|
+
*
|
|
114
|
+
* Shared by buildKeyMap's cache (keyMap.ts), renderTopicCached below and
|
|
115
|
+
* the book search index. It lived privately in the first until the topic
|
|
116
|
+
* cache needed the identical logic; keeping one copy is the point.
|
|
117
|
+
*/
|
|
118
|
+
export function stampFiles(files) {
|
|
119
|
+
return files.map(sourceStamp).join('|');
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Pure directory-walking core of findDitamapFiles (keyMap.ts). Lives here
|
|
123
|
+
* rather than there for the same reason stampFiles above does: keyMap.ts
|
|
124
|
+
* imports vscode at module scope for parseDocRoot/vscode.Uri, so nothing
|
|
125
|
+
* defined there can be unit tested without a vscode.Uri/workspace, even
|
|
126
|
+
* logic like this that never touches vscode itself.
|
|
127
|
+
*
|
|
128
|
+
* Walks upward from startDir to root (inclusive); at *each* level it scans
|
|
129
|
+
* that directory's whole subtree, not just its direct children, for
|
|
130
|
+
* .ditamap files -- layouts that keep maps/ and topics/ as siblings (see
|
|
131
|
+
* test-dita-file/manual) put the nearest map one directory below the
|
|
132
|
+
* ancestor level being scanned, so a direct-children-only scan at each
|
|
133
|
+
* ancestor silently misses it and buildKeyMap falls back to whichever
|
|
134
|
+
* unrelated .ditamap happens to sit directly in a further-up ancestor, if
|
|
135
|
+
* any, instead of the real one (kill test: keyMap.test.ts).
|
|
136
|
+
*/
|
|
137
|
+
export function collectDitamapFilesUpward(startDir, root, stopAtFirstMatch) {
|
|
138
|
+
const results = [];
|
|
139
|
+
// A directory two ancestor levels up recursively covers everything a
|
|
140
|
+
// closer level already scanned, so without this a .ditamap nested a
|
|
141
|
+
// couple of directories down would be reported once per ancestor level
|
|
142
|
+
// that subsumes it, not once.
|
|
143
|
+
const visited = new Set();
|
|
144
|
+
let dir = startDir;
|
|
145
|
+
while (dir.length >= root.length) {
|
|
146
|
+
collectDitamapFilesRecursive(dir, results, visited);
|
|
147
|
+
if (stopAtFirstMatch && results.length > 0)
|
|
148
|
+
return results;
|
|
149
|
+
const parent = dirname(dir);
|
|
150
|
+
if (parent === dir)
|
|
151
|
+
break;
|
|
152
|
+
dir = parent;
|
|
153
|
+
}
|
|
154
|
+
return results;
|
|
155
|
+
}
|
|
156
|
+
function collectDitamapFilesRecursive(dir, results, visited) {
|
|
157
|
+
if (visited.has(dir))
|
|
158
|
+
return;
|
|
159
|
+
visited.add(dir);
|
|
160
|
+
let entries;
|
|
161
|
+
try {
|
|
162
|
+
entries = readdirSync(dir, { withFileTypes: true });
|
|
163
|
+
}
|
|
164
|
+
catch (e) {
|
|
165
|
+
console.warn(`Failed to read directory ${dir}:`, e instanceof Error ? e.message : e);
|
|
166
|
+
return;
|
|
167
|
+
}
|
|
168
|
+
for (const entry of entries) {
|
|
169
|
+
const full = join(dir, entry.name);
|
|
170
|
+
if (entry.isDirectory()) {
|
|
171
|
+
collectDitamapFilesRecursive(full, results, visited);
|
|
172
|
+
}
|
|
173
|
+
else if (entry.name.toLowerCase().endsWith('.ditamap')) {
|
|
174
|
+
results.push(full);
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Budget for the topic render cache below, in bytes of rendered HTML.
|
|
180
|
+
*
|
|
181
|
+
* Bounded and clearable like every other cache in this file, per the rule
|
|
182
|
+
* stated at imageDimensionsCache -- but bounded by bytes rather than by entry
|
|
183
|
+
* count, because count is not a meaningful unit here. The other caches hold
|
|
184
|
+
* fixed-size entries (a dimension pair, a keymap), so capping their count caps
|
|
185
|
+
* their memory; a topic's HTML varies by orders of magnitude between a stub
|
|
186
|
+
* and a full reference topic, so any count cap is either far too generous in
|
|
187
|
+
* bytes or, set low enough to be safe, far too tight in entries.
|
|
188
|
+
*
|
|
189
|
+
* Too tight in entries is the failure that matters, and it is not gradual: a
|
|
190
|
+
* book with more topics than the cap gets NO reuse at all. Each pass renders
|
|
191
|
+
* in map order, so once the cache is full every insertion evicts an entry the
|
|
192
|
+
* same pass has not reached again yet -- a cyclic access pattern, LRU's
|
|
193
|
+
* classic worst case. Budgeting by bytes puts the cliff where it belongs: a
|
|
194
|
+
* book whose entire HTML exceeds the budget is already costing at least that
|
|
195
|
+
* much to hold as one assembled string (plus the webview DOM built from it),
|
|
196
|
+
* so that is the point at which caching more stops being worth it.
|
|
197
|
+
*
|
|
198
|
+
* 32MB holds roughly 4,500 typical topics -- any realistic book, with room
|
|
199
|
+
* for several open at once. Cleared from clearAllCaches() on deactivation.
|
|
200
|
+
*/
|
|
201
|
+
export const TOPIC_RENDER_CACHE_MAX_BYTES = 32 * 1024 * 1024;
|
|
202
|
+
const topicRenderCache = new Map();
|
|
203
|
+
let topicRenderCacheBytes = 0;
|
|
204
|
+
let topicRenderCacheBudget = TOPIC_RENDER_CACHE_MAX_BYTES;
|
|
205
|
+
export function clearTopicRenderCache() {
|
|
206
|
+
topicRenderCache.clear();
|
|
207
|
+
topicRenderCacheBytes = 0;
|
|
208
|
+
}
|
|
209
|
+
/** How many topic renders are currently held -- test hook for eviction/clear. */
|
|
210
|
+
export function topicRenderCacheSize() {
|
|
211
|
+
return topicRenderCache.size;
|
|
212
|
+
}
|
|
213
|
+
/** Bytes of HTML currently held -- test hook, paired with the size above. */
|
|
214
|
+
export function topicRenderCacheBytesHeld() {
|
|
215
|
+
return topicRenderCacheBytes;
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* Test hook: shrinks the budget so eviction can be exercised without first
|
|
219
|
+
* rendering 32MB of real topics. Called with no argument it restores the
|
|
220
|
+
* production budget. Nothing outside the test suite calls this.
|
|
221
|
+
*/
|
|
222
|
+
export function setTopicRenderCacheBudgetForTesting(bytes) {
|
|
223
|
+
topicRenderCacheBudget = bytes ?? TOPIC_RENDER_CACHE_MAX_BYTES;
|
|
224
|
+
}
|
|
225
|
+
function dropTopicEntry(key) {
|
|
226
|
+
const entry = topicRenderCache.get(key);
|
|
227
|
+
if (!entry)
|
|
228
|
+
return;
|
|
229
|
+
topicRenderCache.delete(key);
|
|
230
|
+
topicRenderCacheBytes -= entry.bytes;
|
|
231
|
+
}
|
|
232
|
+
function dropOldestTopicEntry() {
|
|
233
|
+
const oldest = topicRenderCache.keys().next().value;
|
|
234
|
+
if (oldest !== undefined)
|
|
235
|
+
dropTopicEntry(oldest);
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* renderTopicToHtml with reuse across passes -- the difference between "one
|
|
239
|
+
* keystroke in one topic" and "the whole book again" in book mode, which
|
|
240
|
+
* otherwise re-renders every referenced topic on each debounced pass (see
|
|
241
|
+
* scripts/bench-book-render.js for the measured cost, and the budget note
|
|
242
|
+
* above for why reuse is bounded in bytes).
|
|
243
|
+
*
|
|
244
|
+
* Deliberately opt-in and separate rather than built into renderTopicToHtml:
|
|
245
|
+
* "Export as HTML" calls that one with its own asWebviewUri, and sharing a
|
|
246
|
+
* single cache between the two would hand book-mode HTML to an exported
|
|
247
|
+
* standalone file.
|
|
248
|
+
*
|
|
249
|
+
* Two assumptions worth stating, since neither is enforced by the key.
|
|
250
|
+
*
|
|
251
|
+
* asWebviewUri output depends only on the local URI and the window's remote
|
|
252
|
+
* info, never on which webview asked: VS Code builds it as
|
|
253
|
+
* `https://<scheme>+<authority>.vscode-resource.vscode-cdn.net<path>` in a
|
|
254
|
+
* module-level helper with no panel in scope, and cspSource is likewise the
|
|
255
|
+
* constant `'self' https://*.vscode-cdn.net` (both checked against the
|
|
256
|
+
* shipped extension host bundle, not assumed). So HTML built for one map
|
|
257
|
+
* panel is valid in another, and the caller's asWebviewUri closure is not
|
|
258
|
+
* part of the cache key.
|
|
259
|
+
*
|
|
260
|
+
* headingLevel is part of the key rather than a merely validated field
|
|
261
|
+
* because the same topic legitimately sits at different depths across two
|
|
262
|
+
* open books -- validating it instead would make those two entries evict each
|
|
263
|
+
* other on every pass.
|
|
264
|
+
*/
|
|
265
|
+
export function renderTopicCached(input) {
|
|
266
|
+
const key = `${input.filePath}\u0000${input.headingLevel}`;
|
|
267
|
+
const cached = topicRenderCache.get(key);
|
|
268
|
+
if (cached &&
|
|
269
|
+
cached.keyMap === input.keyMap &&
|
|
270
|
+
cached.uiLanguage === input.uiLanguage &&
|
|
271
|
+
cached.suppressIndexterm === input.suppressIndexterm &&
|
|
272
|
+
cached.bookMembers === input.bookMembers &&
|
|
273
|
+
stampFiles(cached.files) === cached.stamps) {
|
|
274
|
+
// Re-insert so a hit keeps the entry from being the oldest (and therefore
|
|
275
|
+
// first-evicted) candidate -- same LRU-by-reinsertion as
|
|
276
|
+
// imageDimensionsCache above.
|
|
277
|
+
topicRenderCache.delete(key);
|
|
278
|
+
topicRenderCache.set(key, cached);
|
|
279
|
+
// A hit reads nothing, but the answer still stands for these files.
|
|
280
|
+
noteSourceDependencies(cached.files);
|
|
281
|
+
return { html: cached.html, title: cached.title };
|
|
282
|
+
}
|
|
283
|
+
// Honour a caller-supplied sink as well, so anyone who passed one still
|
|
284
|
+
// sees the dependency set instead of having it silently replaced.
|
|
285
|
+
const dependencies = input.collectDependencies ?? new Set();
|
|
286
|
+
// Previews only (see above), so conref'd content is always marked here.
|
|
287
|
+
const result = renderTopicToHtml({ ...input, markConrefs: true, collectDependencies: dependencies });
|
|
288
|
+
if (result.error) {
|
|
289
|
+
// Never cache a failure. A malformed mid-edit save is exactly the
|
|
290
|
+
// transient case this path sees, and pinning it would keep serving the
|
|
291
|
+
// error page after the file was fixed -- the dependency stamps would
|
|
292
|
+
// still match, because the file that failed to parse is the very file
|
|
293
|
+
// whose stamp gets compared.
|
|
294
|
+
dropTopicEntry(key);
|
|
295
|
+
return result;
|
|
296
|
+
}
|
|
297
|
+
const files = [...dependencies];
|
|
298
|
+
// UTF-8 bytes, not html.length: DITA content is frequently CJK, where the
|
|
299
|
+
// character count understates what is actually retained by up to 3x.
|
|
300
|
+
const bytes = Buffer.byteLength(result.html, 'utf8');
|
|
301
|
+
if (bytes > topicRenderCacheBudget) {
|
|
302
|
+
// A single topic larger than the entire budget. Caching it would evict
|
|
303
|
+
// everything else and then be evicted itself on the next insert, so skip
|
|
304
|
+
// it: that entry alone falls back to uncached rendering.
|
|
305
|
+
dropTopicEntry(key);
|
|
306
|
+
return result;
|
|
307
|
+
}
|
|
308
|
+
// Make room before inserting, and account for any stale entry this key
|
|
309
|
+
// already holds -- overwriting it in place would otherwise leak its bytes
|
|
310
|
+
// out of the running total and shrink the effective budget permanently.
|
|
311
|
+
dropTopicEntry(key);
|
|
312
|
+
while (topicRenderCache.size > 0 && topicRenderCacheBytes + bytes > topicRenderCacheBudget) {
|
|
313
|
+
dropOldestTopicEntry();
|
|
314
|
+
}
|
|
315
|
+
topicRenderCache.set(key, {
|
|
316
|
+
html: result.html,
|
|
317
|
+
title: result.title,
|
|
318
|
+
files,
|
|
319
|
+
stamps: stampFiles(files),
|
|
320
|
+
keyMap: input.keyMap,
|
|
321
|
+
uiLanguage: input.uiLanguage,
|
|
322
|
+
suppressIndexterm: input.suppressIndexterm,
|
|
323
|
+
bookMembers: input.bookMembers,
|
|
324
|
+
bytes,
|
|
325
|
+
});
|
|
326
|
+
topicRenderCacheBytes += bytes;
|
|
327
|
+
return result;
|
|
328
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
// Public surface of @dita-viewer/core.
|
|
2
|
+
//
|
|
3
|
+
// Hosts (the Obsidian plugin, and in time the VS Code extension) render DITA
|
|
4
|
+
// through these exports only. The VS Code DITA Viewer depends on this package
|
|
5
|
+
// and holds no copies of ./parser, ./render and ./editor (see README), so they
|
|
6
|
+
// are edited here and released as a new version.
|
|
7
|
+
export { renderTopicXml, buildTitleMap, collectDitamapFilesUpward } from './editor/topicRender';
|
|
8
|
+
export { buildKeySpace, getKeyDefs } from './editor/keySpace';
|
|
9
|
+
export { readSourceText, setSourceOverlay, clearSourceOverlay } from './editor/sourceText';
|
|
10
|
+
export { decodeHrefPart } from './editor/refResolvers';
|
|
11
|
+
export { buildKeyMapForDocument, buildKeySpaceForDocument } from './keyMapForDocument';
|
|
12
|
+
export { complete } from './completion';
|
|
13
|
+
export { collectDiagnostics } from './diagnostics';
|
|
14
|
+
export { collectReferenceableFiles, toRelativeHref } from './language/referenceableFiles';
|
|
15
|
+
export { IMAGE_EXT } from './completionData';
|
|
16
|
+
export { collectIds, splitRefFragment } from './language/ditaLanguageUtils';
|
|
17
|
+
export { collectRefEntries, offsetToLineCol } from './language/ditaLanguageUtils';
|
|
18
|
+
export { renderMapXml } from './mapRender';
|
|
19
|
+
export { renderBookXml } from './bookRender';
|
|
20
|
+
export { renderSiteXml } from './siteRender';
|
|
21
|
+
export { PROFILE_ATTRS, ditavalAction, isEmptyFilter, isExcluded, isValueExcluded, parseDitaval, profileGroups, profileKey, profileValuesOf, profileValuesOfKeys, pruneExcluded, } from './profiling';
|
|
22
|
+
export { collectMapEntries, getMapTitleText } from './render/mapTypeMap';
|
|
23
|
+
// The parser and renderer entry points a host that renders by itself needs, and
|
|
24
|
+
// what they take and return. Everything the VS Code viewer imports from the
|
|
25
|
+
// copied modules is here, so it can depend on this package instead of copying.
|
|
26
|
+
export { parseDita, parseDitamap, preprocessEntities } from './parser/ditaParser';
|
|
27
|
+
export { STANDARD_TAG_TO_BASETYPE } from './parser/standardTagMap';
|
|
28
|
+
export { MAP_STANDARD_TAG_TO_BASETYPE } from './parser/mapTagMap';
|
|
29
|
+
export { renderDocument, renderElement } from './render/renderer';
|
|
30
|
+
export { collectIndextermChips, findTopLevelIndextermsInSubtree } from './render/baseTypeMap';
|
|
31
|
+
export { createBookRoleLabeler, extractText, getDisplayNameInfo, isDitamapRef, renderMapDocument } from './render/mapTypeMap';
|
|
32
|
+
export { isExternalRef } from './language/ditaLanguageUtils';
|
|
33
|
+
// The rest of what the VS Code viewer imports from the copied modules: the
|
|
34
|
+
// render cache, the file and key resolvers, the source overlay, the editor
|
|
35
|
+
// language helpers, and the helpers its tests call. Their shapes follow the
|
|
36
|
+
// viewer's needs and may change while the version is 0.x.
|
|
37
|
+
export { lookupNamedEntity } from './parser/namedEntities';
|
|
38
|
+
export { BASE_TYPE_RENDERERS } from './render/baseTypeMap';
|
|
39
|
+
export { computeKeyrefSpacing, needsSpace } from './render/cjkSpacing';
|
|
40
|
+
export { mergeProfilingAttrs, profilingChipsHtml, profilingKeysAttr } from './render/renderer';
|
|
41
|
+
export { resolveConkeyref } from './editor/conkeyref';
|
|
42
|
+
export { collectMapKeys, isKeyContextAvailable, keySourceMaps, qualifiedNames, qualifiedNamesMulti } from './editor/keySpace';
|
|
43
|
+
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';
|
|
44
|
+
export { buildRenderContext } from './editor/renderContext';
|
|
45
|
+
export { clearAllSourceOverlays, dependsOn, noteSourceDependencies, sourceOverlaySize, sourceStamp, trackSourceReads } from './editor/sourceText';
|
|
46
|
+
export { TOPIC_RENDER_CACHE_MAX_BYTES, clearTopicRenderCache, collectText, renderTopicCached, renderTopicToHtml, setTopicRenderCacheBudgetForTesting, stampFiles, topicRenderCacheBytesHeld, topicRenderCacheSize } from './editor/topicRender';
|
|
47
|
+
export { collectMapSymbols, collectTopicSymbols, collectUnknownElements, findConrefTargetOffset, findEnclosingKeydefKeys, findIdAttrAt, findKeyDefinitionOffset, findKeysAttrAt, findRefAttrAt, findUnclosedTag, getAttributesForTag, getAutoCloseTag, getCloseTagCompletion, getCompletionContext, getMapRefName, stripSameDocumentFragmentPrefix } from './language/ditaLanguageUtils';
|
|
48
|
+
/**
|
|
49
|
+
* Host tokens the stylesheet reads (styles/dita-content.css). A host defines
|
|
50
|
+
* these on the element that carries the rendered content; styles/TOKENS.md
|
|
51
|
+
* says what each one means.
|
|
52
|
+
*/
|
|
53
|
+
export const HOST_TOKENS = [
|
|
54
|
+
'--dita-fg',
|
|
55
|
+
'--dita-fg-muted',
|
|
56
|
+
'--dita-bg',
|
|
57
|
+
'--dita-bg-elevated',
|
|
58
|
+
'--dita-border',
|
|
59
|
+
'--dita-focus',
|
|
60
|
+
'--dita-hover-bg',
|
|
61
|
+
'--dita-selected-fg',
|
|
62
|
+
'--dita-link',
|
|
63
|
+
'--dita-code-bg',
|
|
64
|
+
'--dita-code-inline-bg',
|
|
65
|
+
'--dita-font',
|
|
66
|
+
];
|