@hia-doc/renderer-html 0.1.3 → 0.1.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.
- package/README.md +27 -4
- package/dist/index.d.ts +329 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1683 -199
- package/dist/index.js.map +1 -1
- package/dist/information-architecture.d.ts +211 -0
- package/dist/information-architecture.d.ts.map +1 -0
- package/dist/information-architecture.js +243 -0
- package/dist/information-architecture.js.map +1 -0
- package/dist/portal-ui-locale.d.ts +60 -0
- package/dist/portal-ui-locale.d.ts.map +1 -0
- package/dist/portal-ui-locale.js +278 -0
- package/dist/portal-ui-locale.js.map +1 -0
- package/dist/presentation-profile.d.ts +78 -0
- package/dist/presentation-profile.d.ts.map +1 -0
- package/dist/presentation-profile.js +242 -0
- package/dist/presentation-profile.js.map +1 -0
- package/dist/theme-assets.d.ts +31 -0
- package/dist/theme-assets.d.ts.map +1 -0
- package/dist/theme-assets.js +55 -0
- package/dist/theme-assets.js.map +1 -0
- package/package.json +4 -3
package/dist/index.js
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
|
-
import { getI18nField, resolveI18nFieldText } from "@hia-doc/core";
|
|
2
|
-
import {
|
|
1
|
+
import { canonicalizeDocumentationLocale, getI18nField, resolveI18nFieldText, validateBusinessFlowDocumentationProjection, validateDocumentationSourceCommentProjection } from "@hia-doc/core";
|
|
2
|
+
import { relocateDefaultThemeAssets } from "./theme-assets.js";
|
|
3
|
+
import { DEFAULT_THEME_CSS_PATH, DEFAULT_THEME_JS_PATH, PORTAL_THEME_SCHEMES, PORTAL_THEME_SKIN_IDS, getDefaultDocumentationPortalThemeReference, getDefaultThemeAssets, getPortalThemeSchemeLabel, getPortalThemeSkinLabel } from "@hia-doc/theme-default";
|
|
4
|
+
import { DOCUMENTATION_PORTAL_SEMANTIC_PATH_KINDS, getDocumentationPortalLabels, resolveDocumentationPortalInformationArchitecture, resolveDocumentationPortalUiLocale } from "./information-architecture.js";
|
|
5
|
+
import { PORTAL_PRESENTATION_PROFILE_PATH, createPortalPresentationBundle } from "./presentation-profile.js";
|
|
6
|
+
import { DOCUMENTATION_PORTAL_UI_LOCALE_PROFILE_ID, DOCUMENTATION_PORTAL_UI_LOCALE_REPORT_PATH, DOCUMENTATION_PORTAL_UI_LOCALE_SURFACE_ID, DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES, createDocumentationPortalUiLocaleAdoption, resolveDocumentationPortalUiMessage } from "./portal-ui-locale.js";
|
|
7
|
+
export * from "./information-architecture.js";
|
|
8
|
+
export * from "./portal-ui-locale.js";
|
|
9
|
+
export * from "./presentation-profile.js";
|
|
10
|
+
export { renderThemeAssets } from "./theme-assets.js";
|
|
3
11
|
export const HIA_RENDER_HTML_MANIFEST_SCHEMA_VERSION = "0.1.0";
|
|
4
12
|
/**
|
|
5
13
|
* 项目导航索引的中性 contract 名称;供静态 portal、搜索与宿主导航消费。
|
|
@@ -24,6 +32,8 @@ export const HIA_PROJECT_RELATION_GRAPH_CONTRACT_VERSION = "0.1.0-draft";
|
|
|
24
32
|
export function renderHtmlDocument(document, options = {}) {
|
|
25
33
|
const pageTitle = options.title ?? document.title;
|
|
26
34
|
const includeThemeAssets = options.includeThemeAssets ?? true;
|
|
35
|
+
// <lang><zh-CN>即使调用者选择外部资源,也先验证明确颜色,避免静默忽略非法配置。</zh-CN><en>Validate explicit colors even with external resources, avoiding silently ignored invalid configuration.</en></lang>
|
|
36
|
+
const assets = getDefaultThemeAssets(options.theme ?? {});
|
|
27
37
|
const files = [
|
|
28
38
|
{
|
|
29
39
|
path: "index.html",
|
|
@@ -33,7 +43,7 @@ export function renderHtmlDocument(document, options = {}) {
|
|
|
33
43
|
}
|
|
34
44
|
];
|
|
35
45
|
if (includeThemeAssets) {
|
|
36
|
-
for (const asset of
|
|
46
|
+
for (const asset of assets) {
|
|
37
47
|
files.push({
|
|
38
48
|
path: asset.path,
|
|
39
49
|
contents: asset.contents,
|
|
@@ -42,37 +52,94 @@ export function renderHtmlDocument(document, options = {}) {
|
|
|
42
52
|
});
|
|
43
53
|
}
|
|
44
54
|
}
|
|
55
|
+
// <lang><zh-CN>资源路由在manifest前完成,使文件清单只包含本次真正拥有的文件。</zh-CN><en>Route assets before the manifest so the inventory contains only files owned by this output.</en></lang>
|
|
56
|
+
const routedFiles = relocateDefaultThemeAssets(files, options.themeAssets);
|
|
45
57
|
return {
|
|
46
|
-
files,
|
|
58
|
+
files: routedFiles,
|
|
47
59
|
diagnostics: [],
|
|
48
|
-
manifest: createManifest(document,
|
|
60
|
+
manifest: createManifest(document, routedFiles, options)
|
|
49
61
|
};
|
|
50
62
|
}
|
|
63
|
+
/**
|
|
64
|
+
* @lang zh-CN
|
|
65
|
+
* 把统一项目输入渲染为默认 split-site 或显式 single-page,并生成 exact presentation profile、内容寻址源码资源和 manifest linkage。
|
|
66
|
+
*
|
|
67
|
+
* @lang en
|
|
68
|
+
* Renders unified project input as the default split site or explicit single page, including an exact presentation profile, content-addressed source assets, and manifest linkage.
|
|
69
|
+
*
|
|
70
|
+
* @param projectInput - 已结构化的项目、entry 与关系输入;renderer 不自行读取路径。Structured project, entry, and relation input; the renderer performs no path read.
|
|
71
|
+
* @param options - locale、IA、源码模式和 Portal theme 选择。Locale, IA, source-mode, and Portal-theme selections.
|
|
72
|
+
* @returns 完整的内存文件集、diagnostics 与 body-free manifest。Complete in-memory file set, diagnostics, and body-free manifest.
|
|
73
|
+
* @throws 当显式 IA/theme/source-comment 选择或 renderer 生成的 exact profile 非法时 fail closed。Fails closed when explicit IA/theme/source-comment selections or the renderer-generated exact profile are invalid.
|
|
74
|
+
*/
|
|
51
75
|
export function renderProjectHtmlDocument(projectInput, options = {}) {
|
|
52
|
-
|
|
53
|
-
const normalizedProjectInput = normalizeProjectRelationGraphInput(
|
|
76
|
+
// <lang><zh-CN>关系图先规范化,确保 presentation identity 使用最终 relation facts,而不是调用者数组顺序。</zh-CN><en>Normalize the relation graph first so presentation identity uses final relation facts rather than caller array order.</en></lang>
|
|
77
|
+
const normalizedProjectInput = normalizeProjectRelationGraphInput(projectInput);
|
|
54
78
|
const pageTitle = options.title ?? normalizedProjectInput.project.title ?? normalizedProjectInput.project.name;
|
|
55
79
|
const includeThemeAssets = options.includeThemeAssets ?? true;
|
|
56
80
|
const siteLayout = options.projectSite?.layout ?? "split-site";
|
|
57
|
-
const
|
|
81
|
+
const portalContext = resolveProjectPortalContext(normalizedProjectInput, options, siteLayout);
|
|
82
|
+
// <lang><zh-CN>颜色由主题owner单点校验,和普通文档使用同一个品牌资源工厂。</zh-CN><en>The theme owner validates colors centrally through the same branded-asset factory used by documents.</en></lang>
|
|
83
|
+
const assets = getDefaultThemeAssets(options.theme ?? {});
|
|
84
|
+
// <lang><zh-CN>bundle 是 profile、source asset 和 owner mapping 的唯一生成点;后续 HTML 只消费 body-free mapping。</zh-CN><en>The bundle is the sole generation point for profiles, source assets, and owner mappings; later HTML consumes only body-free mappings.</en></lang>
|
|
85
|
+
const presentationBundle = createPortalPresentationBundle({
|
|
86
|
+
projectId: normalizedProjectInput.project.id ?? `project:${normalizedProjectInput.project.name}`,
|
|
87
|
+
layout: siteLayout,
|
|
88
|
+
sourceMode: options.projectSite?.source?.presentation ?? "fetch",
|
|
89
|
+
maxLines: options.projectSite?.source?.maxLines ?? 400,
|
|
90
|
+
skinId: portalContext.theme.skinId,
|
|
91
|
+
scheme: portalContext.theme.scheme,
|
|
92
|
+
topics: normalizedProjectInput.entries.map((entry) => ({
|
|
93
|
+
entryId: entry.id,
|
|
94
|
+
topicKind: entry.kind,
|
|
95
|
+
relationIds: collectProjectPresentationRelationIds(entry, normalizedProjectInput.relationGraph)
|
|
96
|
+
})),
|
|
97
|
+
sources: normalizedProjectInput.entries
|
|
98
|
+
.filter((entry) => Boolean(entry.source))
|
|
99
|
+
.map((entry) => ({
|
|
100
|
+
entryId: entry.id,
|
|
101
|
+
sourcePath: entry.source.path,
|
|
102
|
+
...(entry.source.preview?.content !== undefined ? { content: entry.source.preview.content } : {}),
|
|
103
|
+
...(entry.source.range?.start.line ? { startLine: entry.source.range.start.line } : {}),
|
|
104
|
+
...(entry.source.range?.end?.line ? { endLine: entry.source.range.end.line } : {}),
|
|
105
|
+
...(entry.docSourceMap?.entryId ? { sourceMapId: entry.docSourceMap.entryId } : {})
|
|
106
|
+
}))
|
|
107
|
+
});
|
|
108
|
+
const sourcePreparedProjectInput = applyProjectSourcePresentationPolicy(normalizedProjectInput, options, presentationBundle);
|
|
109
|
+
const renderedProjectInput = {
|
|
110
|
+
...sourcePreparedProjectInput,
|
|
111
|
+
diagnostics: [...(sourcePreparedProjectInput.diagnostics ?? []), ...presentationBundle.diagnostics]
|
|
112
|
+
};
|
|
113
|
+
const navigationIndex = createProjectNavigationIndex(renderedProjectInput, pageTitle, options, portalContext, presentationBundle);
|
|
58
114
|
const files = siteLayout === "single-page"
|
|
59
115
|
? [
|
|
60
116
|
{
|
|
61
117
|
path: "index.html",
|
|
62
|
-
contents: renderProjectIndexHtml(pageTitle,
|
|
118
|
+
contents: renderProjectIndexHtml(pageTitle, renderedProjectInput, options, portalContext),
|
|
63
119
|
contentType: "text/html; charset=utf-8",
|
|
64
120
|
role: "entry"
|
|
65
121
|
}
|
|
66
122
|
]
|
|
67
|
-
: createProjectSplitSiteFiles(pageTitle,
|
|
123
|
+
: createProjectSplitSiteFiles(pageTitle, renderedProjectInput, navigationIndex, options, portalContext);
|
|
124
|
+
// <lang><zh-CN>完整性 report 在所有可见/无脚本文件生成后追加,但 adoption 本身已在生成前通过 gate。</zh-CN><en>Append the completeness report after visible/no-script files, while the adoption itself has already passed its pre-render gate.</en></lang>
|
|
125
|
+
if (portalContext.uiLocaleAdoption) {
|
|
126
|
+
files.push({
|
|
127
|
+
path: DOCUMENTATION_PORTAL_UI_LOCALE_REPORT_PATH,
|
|
128
|
+
contents: `${portalContext.uiLocaleAdoption.reportJson}\n`,
|
|
129
|
+
contentType: "application/json; charset=utf-8",
|
|
130
|
+
role: "index"
|
|
131
|
+
});
|
|
132
|
+
}
|
|
68
133
|
files.push({
|
|
69
134
|
path: "project-index.json",
|
|
70
135
|
contents: `${JSON.stringify(navigationIndex, null, 2)}\n`,
|
|
71
136
|
contentType: "application/json; charset=utf-8",
|
|
72
137
|
role: "index"
|
|
73
138
|
});
|
|
139
|
+
// <lang><zh-CN>profile/source artifacts 在 navigation index 后追加;manifest 仍记录完整确定性文件清单。</zh-CN><en>Append profile/source artifacts after the navigation index while the manifest still records the full deterministic file inventory.</en></lang>
|
|
140
|
+
files.push(...presentationBundle.artifacts);
|
|
74
141
|
if (includeThemeAssets) {
|
|
75
|
-
for (const asset of
|
|
142
|
+
for (const asset of assets) {
|
|
76
143
|
files.push({
|
|
77
144
|
path: asset.path,
|
|
78
145
|
contents: asset.contents,
|
|
@@ -81,37 +148,225 @@ export function renderProjectHtmlDocument(projectInput, options = {}) {
|
|
|
81
148
|
});
|
|
82
149
|
}
|
|
83
150
|
}
|
|
151
|
+
// <lang><zh-CN>共享模式删除副本并重定位全部完整页面引用,manifest不再声称拥有外部文件。</zh-CN><en>Shared mode removes copies and relocates complete-page references; the manifest no longer claims external-file ownership.</en></lang>
|
|
152
|
+
const routedFiles = relocateDefaultThemeAssets(files, options.themeAssets);
|
|
153
|
+
return {
|
|
154
|
+
files: routedFiles,
|
|
155
|
+
diagnostics: renderedProjectInput.diagnostics ?? [],
|
|
156
|
+
manifest: createProjectManifest(renderedProjectInput, routedFiles, pageTitle, options, navigationIndex, presentationBundle, portalContext)
|
|
157
|
+
};
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* @lang zh-CN 在任何文件生成前解析 theme/locale 并完成 exact IA、source-comment 与 single-page gate,避免 partial output。
|
|
161
|
+
* @lang en Resolves theme/locale and enforces exact IA, source-comment, and single-page gates before file generation, preventing partial output.
|
|
162
|
+
*
|
|
163
|
+
* @param projectInput - 待验证的结构化 project input。Structured project input to validate.
|
|
164
|
+
* @param options - renderer 调用选项。Renderer invocation options.
|
|
165
|
+
* @param layout - 已解析的页面布局。Resolved page layout.
|
|
166
|
+
* @returns 只含已验证选择的 context。Context containing validated selections only.
|
|
167
|
+
* @throws 对任何不受支持的显式选择 fail closed。Fails closed for every unsupported explicit selection.
|
|
168
|
+
*/
|
|
169
|
+
function resolveProjectPortalContext(projectInput, options, layout) {
|
|
170
|
+
const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
|
|
171
|
+
const explicitInformationArchitecture = options.projectSite?.informationArchitecture;
|
|
172
|
+
if (explicitInformationArchitecture && !options.projectSite?.uiLocale) {
|
|
173
|
+
throw new TypeError("HIA_PORTAL_UI_LOCALE_REQUIRED: Explicit Portal information architecture requires a caller-explicit UI locale.");
|
|
174
|
+
}
|
|
175
|
+
if (options.projectSite?.uiLocaleCompleteness && !explicitInformationArchitecture) {
|
|
176
|
+
throw new TypeError("HIA_PORTAL_UI_LOCALE_IA_REQUIRED: UI locale completeness identity requires explicit Portal information architecture.");
|
|
177
|
+
}
|
|
178
|
+
// <lang><zh-CN>非 IA 调用保留历史 fallback;adopted explicit IA 永远由上面的 caller-explicit gate 提供值。</zh-CN><en>Non-IA calls retain the historical fallback; adopted explicit IA always receives its value from the caller-explicit gate above.</en></lang>
|
|
179
|
+
const uiLocale = resolveDocumentationPortalUiLocale(options.projectSite?.uiLocale, localeModel.selectedLocale);
|
|
180
|
+
const sourceCommentProjection = options.projectSite?.sourceCommentProjection;
|
|
181
|
+
// <lang><zh-CN>共用逐项优先级及闭集校验;旧项目调用保留兼容回退。</zh-CN><en>Share per-field precedence and closed-catalog validation, retaining fallback for legacy project calls.</en></lang>
|
|
182
|
+
const { skinId: requestedSkin, scheme: requestedScheme } = resolveThemeSelection(options);
|
|
183
|
+
if (projectInput.documentationContinuity) {
|
|
184
|
+
assertProjectDocumentationContinuitySummary(projectInput.documentationContinuity);
|
|
185
|
+
}
|
|
186
|
+
if (projectInput.ownerAdoption) {
|
|
187
|
+
assertProjectOwnerAdoptionSummary(projectInput.ownerAdoption);
|
|
188
|
+
if (!explicitInformationArchitecture) {
|
|
189
|
+
throw new TypeError("HIA_PORTAL_IA_OWNER_ADOPTION_REQUIRES_IA: owner-adoption linkage requires explicit Portal information architecture.");
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
if (projectInput.businessFlowDocumentationProjection) {
|
|
193
|
+
// <lang><zh-CN>在生成任何文件前复用 W-P122 owner validator;renderer 不修复、补全或推断 flow facts。</zh-CN><en>Reuse the W-P122 owner validator before generating any file; the renderer repairs, completes, or infers no flow facts.</en></lang>
|
|
194
|
+
if (validateBusinessFlowDocumentationProjection(projectInput.businessFlowDocumentationProjection).length > 0) {
|
|
195
|
+
throw new TypeError("HIA_PORTAL_IA_BUSINESS_FLOW_INVALID: business-flow linkage must be an exact public projection.");
|
|
196
|
+
}
|
|
197
|
+
if (!explicitInformationArchitecture) {
|
|
198
|
+
throw new TypeError("HIA_PORTAL_IA_BUSINESS_FLOW_REQUIRES_IA: business-flow linkage requires explicit Portal information architecture.");
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
if (sourceCommentProjection && !explicitInformationArchitecture) {
|
|
202
|
+
throw new TypeError("HIA_PORTAL_SOURCE_COMMENT_REQUIRES_IA: source-comment projection requires explicit Portal information architecture.");
|
|
203
|
+
}
|
|
204
|
+
if (sourceCommentProjection) {
|
|
205
|
+
const canonical = canonicalizeDocumentationLocale(sourceCommentProjection.locale);
|
|
206
|
+
if (!canonical || canonical.usedLegacyUnderscore || canonical.canonical !== sourceCommentProjection.locale) {
|
|
207
|
+
throw new TypeError("HIA_PORTAL_SOURCE_COMMENT_LOCALE_INVALID: source-comment locale must be a canonical BCP 47 tag.");
|
|
208
|
+
}
|
|
209
|
+
for (const entry of projectInput.entries) {
|
|
210
|
+
if (!entry.sourceCommentProjection)
|
|
211
|
+
continue;
|
|
212
|
+
const validationDiagnostics = validateDocumentationSourceCommentProjection(entry.sourceCommentProjection);
|
|
213
|
+
if (validationDiagnostics.length > 0 || entry.sourceCommentProjection.requestedLocale !== canonical.canonical) {
|
|
214
|
+
throw new TypeError("HIA_PORTAL_SOURCE_COMMENT_PROJECTION_INVALID: source-comment projection must be valid and match the explicit locale.");
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
if (explicitInformationArchitecture && layout === "single-page") {
|
|
219
|
+
throw new TypeError("HIA_CONFIG_IA_SINGLE_PAGE_UNSUPPORTED: Explicit Portal IA is supported only with split-site in this draft.");
|
|
220
|
+
}
|
|
221
|
+
// <lang><zh-CN>只有显式 IA surface 构造 W-P123 report;legacy P3/single-page 不伪报 completeness。</zh-CN><en>Only explicit-IA surfaces build a W-P123 report; legacy P3/single-page output does not claim completeness.</en></lang>
|
|
222
|
+
const uiLocaleAdoption = explicitInformationArchitecture
|
|
223
|
+
? createDocumentationPortalUiLocaleAdoption({
|
|
224
|
+
contentLocale: localeModel.selectedLocale,
|
|
225
|
+
contentLocales: localeModel.locales,
|
|
226
|
+
defaultUiLocale: uiLocale,
|
|
227
|
+
profileId: options.projectSite?.uiLocaleCompleteness?.profileId ?? DOCUMENTATION_PORTAL_UI_LOCALE_PROFILE_ID,
|
|
228
|
+
surfaceId: options.projectSite?.uiLocaleCompleteness?.surfaceId ?? DOCUMENTATION_PORTAL_UI_LOCALE_SURFACE_ID
|
|
229
|
+
})
|
|
230
|
+
: undefined;
|
|
84
231
|
return {
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
232
|
+
uiLocale,
|
|
233
|
+
labels: getDocumentationPortalLabels(uiLocale),
|
|
234
|
+
theme: { skinId: requestedSkin, scheme: requestedScheme },
|
|
235
|
+
...(uiLocaleAdoption ? { uiLocaleAdoption } : {}),
|
|
236
|
+
...(sourceCommentProjection
|
|
237
|
+
? {
|
|
238
|
+
sourceCommentProjection: {
|
|
239
|
+
contentPolicy: sourceCommentProjection.contentPolicy ?? "none",
|
|
240
|
+
locale: sourceCommentProjection.locale
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
: {}),
|
|
244
|
+
...(explicitInformationArchitecture
|
|
245
|
+
? {
|
|
246
|
+
informationArchitecture: resolveDocumentationPortalInformationArchitecture(explicitInformationArchitecture, uiLocale, localeModel.selectedLocale)
|
|
247
|
+
}
|
|
248
|
+
: {})
|
|
88
249
|
};
|
|
89
250
|
}
|
|
251
|
+
/** optional continuity linkage 只接受 exact、non-negative、body-free summary。Optional continuity linkage accepts only an exact, non-negative, body-free summary. */
|
|
252
|
+
function assertProjectDocumentationContinuitySummary(summary) {
|
|
253
|
+
const validShape = isExactObject(summary, [
|
|
254
|
+
"contract",
|
|
255
|
+
"contractVersion",
|
|
256
|
+
"status",
|
|
257
|
+
"entries",
|
|
258
|
+
"requiredOutputsPreserved",
|
|
259
|
+
"semantics"
|
|
260
|
+
])
|
|
261
|
+
&& isExactObject(summary.entries, ["addedCount", "baselineCount", "currentCount", "removedCount", "unchangedCount"])
|
|
262
|
+
&& isExactObject(summary.semantics, ["resolution", "confidence", "provenance"]);
|
|
263
|
+
const counts = validShape ? Object.values(summary.entries) : [];
|
|
264
|
+
const countsConsistent = validShape
|
|
265
|
+
&& summary.entries.baselineCount === summary.entries.unchangedCount + summary.entries.removedCount
|
|
266
|
+
&& summary.entries.currentCount === summary.entries.unchangedCount + summary.entries.addedCount;
|
|
267
|
+
if (!validShape
|
|
268
|
+
|| summary.contract !== "target-documentation-continuity"
|
|
269
|
+
|| summary.contractVersion !== "0.1.0-draft"
|
|
270
|
+
|| !["accepted", "refused"].includes(summary.status)
|
|
271
|
+
|| typeof summary.requiredOutputsPreserved !== "boolean"
|
|
272
|
+
|| !["evidence-summary-pair-validated", "unresolved"].includes(summary.semantics.resolution)
|
|
273
|
+
|| summary.semantics.confidence !== "caller-provided-unverified"
|
|
274
|
+
|| summary.semantics.provenance !== "metadata-only-comparison"
|
|
275
|
+
|| counts.some((value) => !Number.isSafeInteger(value) || value < 0)
|
|
276
|
+
|| !countsConsistent) {
|
|
277
|
+
throw new TypeError("HIA_PORTAL_IA_CONTINUITY_INVALID: continuity linkage must be an exact metadata-only count summary.");
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* @lang zh-CN owner-adoption linkage 只接受 exact、count-consistent、identity/body-free 的 metadata 投影。
|
|
282
|
+
* @lang en Owner-adoption linkage accepts only an exact, count-consistent, identity- and body-free metadata projection.
|
|
283
|
+
*/
|
|
284
|
+
function assertProjectOwnerAdoptionSummary(summary) {
|
|
285
|
+
const rootFields = ["contract", "contractVersion", "projection", "status", "targetFamily", "ownerInput", "contracts", "semantics"];
|
|
286
|
+
const workspaceExpected = summary.targetFamily === "workspace-container";
|
|
287
|
+
const hasWorkspace = summary.workspaceHandoff !== undefined;
|
|
288
|
+
const validShape = isExactObject(summary, hasWorkspace ? [...rootFields, "workspaceHandoff"] : rootFields)
|
|
289
|
+
&& isExactObject(summary.ownerInput, ["submitted", "consent"])
|
|
290
|
+
&& isExactObject(summary.contracts, ["requiredCount", "providedCount", "missingCount"])
|
|
291
|
+
&& isExactObject(summary.semantics, ["resolution", "confidence", "provenance"])
|
|
292
|
+
&& (!hasWorkspace || (summary.workspaceHandoff !== undefined
|
|
293
|
+
&& isExactObject(summary.workspaceHandoff, ["repositoryOwnerCount", "handoffEdgeCount", "state"])));
|
|
294
|
+
const counts = validShape
|
|
295
|
+
? [summary.contracts.requiredCount, summary.contracts.providedCount, summary.contracts.missingCount]
|
|
296
|
+
: [];
|
|
297
|
+
const statusResolutionValid = (summary.status === "ready-for-owner-review"
|
|
298
|
+
&& summary.ownerInput.submitted
|
|
299
|
+
&& summary.contracts.missingCount === 0
|
|
300
|
+
&& summary.semantics.resolution === "owner-input-validated")
|
|
301
|
+
|| (summary.status === "deferred-owner-input-missing"
|
|
302
|
+
&& !summary.ownerInput.submitted
|
|
303
|
+
&& summary.semantics.resolution === "owner-input-not-received")
|
|
304
|
+
|| (summary.status === "refused" && summary.semantics.resolution === "unresolved");
|
|
305
|
+
const workspaceValid = workspaceExpected
|
|
306
|
+
? (summary.status !== "ready-for-owner-review" && !hasWorkspace) || (summary.workspaceHandoff !== undefined
|
|
307
|
+
&& Number.isSafeInteger(summary.workspaceHandoff.repositoryOwnerCount)
|
|
308
|
+
&& summary.workspaceHandoff.repositoryOwnerCount >= 2
|
|
309
|
+
&& Number.isSafeInteger(summary.workspaceHandoff.handoffEdgeCount)
|
|
310
|
+
&& summary.workspaceHandoff.handoffEdgeCount >= 1
|
|
311
|
+
&& summary.workspaceHandoff.state === "owner-review-required")
|
|
312
|
+
: !hasWorkspace;
|
|
313
|
+
if (!validShape
|
|
314
|
+
|| summary.contract !== "target-owner-adoption-kit"
|
|
315
|
+
|| summary.contractVersion !== "0.1.0-draft"
|
|
316
|
+
|| summary.projection !== "portal-metadata-only"
|
|
317
|
+
|| !["ready-for-owner-review", "deferred-owner-input-missing", "refused"].includes(summary.status)
|
|
318
|
+
|| !["enterprise-business", "workspace-container"].includes(summary.targetFamily)
|
|
319
|
+
|| typeof summary.ownerInput.submitted !== "boolean"
|
|
320
|
+
|| !["not-recorded", "recorded-for-review"].includes(summary.ownerInput.consent)
|
|
321
|
+
|| counts.some((value) => !Number.isSafeInteger(value) || value < 0)
|
|
322
|
+
|| summary.contracts.providedCount + summary.contracts.missingCount !== summary.contracts.requiredCount
|
|
323
|
+
|| summary.semantics.confidence !== "caller-provided-unverified"
|
|
324
|
+
|| summary.semantics.provenance !== "metadata-only-owner-kit"
|
|
325
|
+
|| !statusResolutionValid
|
|
326
|
+
|| !workspaceValid) {
|
|
327
|
+
throw new TypeError("HIA_PORTAL_IA_OWNER_ADOPTION_INVALID: owner-adoption linkage must be an exact metadata-only summary.");
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
/** closed-world runtime object shape 检查,防止 TypeScript 之外的 caller 注入 path/body/identity。Checks closed-world runtime object shapes so non-TypeScript callers cannot inject paths, bodies, or identities. */
|
|
331
|
+
function isExactObject(value, allowedFields) {
|
|
332
|
+
return value !== null
|
|
333
|
+
&& typeof value === "object"
|
|
334
|
+
&& !Array.isArray(value)
|
|
335
|
+
&& Object.keys(value).every((field) => allowedFields.includes(field))
|
|
336
|
+
&& allowedFields.every((field) => Object.hasOwn(value, field));
|
|
337
|
+
}
|
|
90
338
|
/**
|
|
91
|
-
* 在 renderer
|
|
92
|
-
* Enforces source-presentation boundaries at the renderer API
|
|
339
|
+
* @lang zh-CN 在 renderer 公共入口执行源码呈现边界,剥离旧外链并只投影 bundle 已授权的正文或同源资源。
|
|
340
|
+
* @lang en Enforces source-presentation boundaries at the renderer API, stripping legacy external links and projecting only bundle-authorized bodies or same-origin assets.
|
|
341
|
+
*
|
|
342
|
+
* @param projectInput - 规范化后的 project input。Normalized project input.
|
|
343
|
+
* @param options - 显式 source presentation 选择。Explicit source-presentation selection.
|
|
344
|
+
* @param presentationBundle - 已 exact-valid 的 body-free owner mapping。Exact-valid body-free owner mapping.
|
|
345
|
+
* @returns 不改变 locator identity 的安全 project input。Safe project input preserving locator identity.
|
|
93
346
|
*/
|
|
94
|
-
function applyProjectSourcePresentationPolicy(projectInput, options) {
|
|
95
|
-
const presentation = options.projectSite?.source?.presentation ?? "
|
|
347
|
+
function applyProjectSourcePresentationPolicy(projectInput, options, presentationBundle) {
|
|
348
|
+
const presentation = options.projectSite?.source?.presentation ?? "fetch";
|
|
96
349
|
return {
|
|
97
350
|
...projectInput,
|
|
98
351
|
entries: projectInput.entries.map((entry) => {
|
|
99
352
|
if (!entry.source) {
|
|
100
353
|
return entry;
|
|
101
354
|
}
|
|
102
|
-
const { preview, fetchUrl, linkUrl, ...locator } = entry.source;
|
|
355
|
+
const { preview, fetchUrl: _legacyFetchUrl, linkUrl: _legacyLinkUrl, publicAsset: _existingPublicAsset, ...locator } = entry.source;
|
|
103
356
|
const previewDefaultExpanded = options.projectSite?.source?.defaultExpanded ?? preview?.defaultExpanded;
|
|
357
|
+
const publicAsset = presentationBundle.sourceByEntryId.get(entry.id);
|
|
104
358
|
const source = {
|
|
105
359
|
...locator,
|
|
106
|
-
...(presentation
|
|
360
|
+
...(presentation === "link" && publicAsset ? { linkUrl: publicAsset.relativeUrl, publicAsset } : {}),
|
|
107
361
|
...(presentation === "embed" && preview ? {
|
|
108
362
|
preview: {
|
|
109
363
|
...preview,
|
|
110
364
|
...(previewDefaultExpanded !== undefined ? { defaultExpanded: previewDefaultExpanded } : {})
|
|
111
365
|
}
|
|
112
366
|
} : {}),
|
|
113
|
-
...(presentation === "fetch" &&
|
|
114
|
-
fetchUrl,
|
|
367
|
+
...(presentation === "fetch" && publicAsset ? {
|
|
368
|
+
fetchUrl: publicAsset.relativeUrl,
|
|
369
|
+
publicAsset,
|
|
115
370
|
fetchTrigger: options.projectSite?.source?.fetchTrigger ?? entry.source.fetchTrigger ?? "on-expand",
|
|
116
371
|
fetchMaxLines: options.projectSite?.source?.maxLines ?? entry.source.fetchMaxLines ?? 400
|
|
117
372
|
} : {})
|
|
@@ -123,6 +378,33 @@ function applyProjectSourcePresentationPolicy(projectInput, options) {
|
|
|
123
378
|
})
|
|
124
379
|
};
|
|
125
380
|
}
|
|
381
|
+
/**
|
|
382
|
+
* @lang zh-CN 为独立 no-script 页面移除 fetch runtime metadata,并把 build-generated link 调整为页面相对路径。
|
|
383
|
+
* @lang en Removes fetch-runtime metadata for standalone no-script pages and adjusts build-generated links to page-relative paths.
|
|
384
|
+
*
|
|
385
|
+
* @param projectInput - 已应用 source policy 的 project input。Project input after source policy application.
|
|
386
|
+
* @returns 不含不可用 fetch control 的 page input。Page input without unavailable fetch controls.
|
|
387
|
+
*/
|
|
388
|
+
function createProjectNoScriptProjectInput(projectInput) {
|
|
389
|
+
return {
|
|
390
|
+
...projectInput,
|
|
391
|
+
entries: projectInput.entries.map((entry) => {
|
|
392
|
+
if (!entry.source) {
|
|
393
|
+
return entry;
|
|
394
|
+
}
|
|
395
|
+
const { fetchUrl, publicAsset: _publicAsset, linkUrl, ...source } = entry.source;
|
|
396
|
+
// <lang><zh-CN>无脚本页面把同源 fetch asset 降级成普通链接;这不会恢复被拒绝的外部 locator。</zh-CN><en>The no-script page degrades a same-origin fetch asset to a regular link without restoring a rejected external locator.</en></lang>
|
|
397
|
+
const noScriptLinkUrl = linkUrl ?? fetchUrl;
|
|
398
|
+
return {
|
|
399
|
+
...entry,
|
|
400
|
+
source: {
|
|
401
|
+
...source,
|
|
402
|
+
...(noScriptLinkUrl ? { linkUrl: `../${noScriptLinkUrl}` } : {})
|
|
403
|
+
}
|
|
404
|
+
};
|
|
405
|
+
})
|
|
406
|
+
};
|
|
407
|
+
}
|
|
126
408
|
function createManifest(document, files, options) {
|
|
127
409
|
return {
|
|
128
410
|
schemaVersion: HIA_RENDER_HTML_MANIFEST_SCHEMA_VERSION,
|
|
@@ -139,7 +421,71 @@ function createManifest(document, files, options) {
|
|
|
139
421
|
}))
|
|
140
422
|
};
|
|
141
423
|
}
|
|
142
|
-
|
|
424
|
+
/** @lang zh-CN 从已验证 bundle 构造 manifest/index 共用的最小 profile 引用。 @lang en Builds the minimal manifest/index profile reference from a validated bundle. */
|
|
425
|
+
function createProjectPresentationProfileRef(presentationBundle) {
|
|
426
|
+
return {
|
|
427
|
+
contract: presentationBundle.profile.contract,
|
|
428
|
+
contractVersion: presentationBundle.profile.contractVersion,
|
|
429
|
+
path: PORTAL_PRESENTATION_PROFILE_PATH,
|
|
430
|
+
profileId: presentationBundle.profile.profileId,
|
|
431
|
+
status: presentationBundle.profile.status
|
|
432
|
+
};
|
|
433
|
+
}
|
|
434
|
+
/**
|
|
435
|
+
* @lang zh-CN
|
|
436
|
+
* 从已通过 W-P123 gate 的 adoption 构造 manifest/index 共用的 body-free 引用和计数。
|
|
437
|
+
*
|
|
438
|
+
* @lang en
|
|
439
|
+
* Builds the body-free manifest/index reference and counts from a W-P123 gate-complete adoption.
|
|
440
|
+
*
|
|
441
|
+
* @param adoption <lang><zh-CN>当前 Portal surface 的完整性结果。</lang><en>Completeness result for the current Portal surface.</en></lang>
|
|
442
|
+
* @returns <lang><zh-CN>不含 message text 或内容正文的引用。</lang><en>Reference containing no message text or content body.</en></lang>
|
|
443
|
+
*/
|
|
444
|
+
function createProjectUiLocaleCompletenessRef(adoption) {
|
|
445
|
+
// <lang><zh-CN>P1 每次 adoption 只有一个 owner surface;evaluator 已保证集合非空。</zh-CN><en>Each P1 adoption owns one surface; the evaluator has already guaranteed a non-empty set.</en></lang>
|
|
446
|
+
const surfaceId = adoption.report.surfaces[0].surfaceId;
|
|
447
|
+
return {
|
|
448
|
+
contract: adoption.report.contract,
|
|
449
|
+
contractVersion: adoption.report.contractVersion,
|
|
450
|
+
evaluationCount: adoption.summary.evaluations,
|
|
451
|
+
exactCount: adoption.summary.exact,
|
|
452
|
+
path: DOCUMENTATION_PORTAL_UI_LOCALE_REPORT_PATH,
|
|
453
|
+
profileId: adoption.report.profileId,
|
|
454
|
+
status: adoption.report.status,
|
|
455
|
+
surfaceId,
|
|
456
|
+
uiLocaleCount: adoption.summary.uiLocales
|
|
457
|
+
};
|
|
458
|
+
}
|
|
459
|
+
/**
|
|
460
|
+
* @lang zh-CN 从已验证 W-P122 projection 构造 manifest 的 body-free ref/count。
|
|
461
|
+
* @lang en Builds a body-free manifest reference and counts from a validated W-P122 projection.
|
|
462
|
+
* @param projection exact-valid public dual projection。 / Exact-valid public dual projection.
|
|
463
|
+
* @returns 不含 label、node、edge 或 evidence body 的引用。 / Reference containing no labels, nodes, edges, or evidence bodies.
|
|
464
|
+
*/
|
|
465
|
+
function createProjectBusinessFlowProjectionRef(projection) {
|
|
466
|
+
return {
|
|
467
|
+
contract: projection.contract,
|
|
468
|
+
contractVersion: projection.contractVersion,
|
|
469
|
+
flowCount: projection.sharedFacts.flows.length,
|
|
470
|
+
humanItemCount: projection.humanLinear.flows.reduce((total, flow) => total + flow.items.length, 0),
|
|
471
|
+
nodeCount: projection.sharedFacts.nodes.length,
|
|
472
|
+
path: "project-index.json",
|
|
473
|
+
relationCount: projection.sharedFacts.relations.length
|
|
474
|
+
};
|
|
475
|
+
}
|
|
476
|
+
/**
|
|
477
|
+
* @lang zh-CN 收集与 entry 关联的稳定 relation ids;relation kind 不参与 containment。
|
|
478
|
+
* @lang en Collects stable relation ids associated with an entry; relation kind does not become containment.
|
|
479
|
+
*/
|
|
480
|
+
function collectProjectPresentationRelationIds(entry, relationGraph) {
|
|
481
|
+
const entryNodeIds = new Set(relationGraph?.nodes.filter((node) => node.entryId === entry.id).map(({ id }) => id) ?? []);
|
|
482
|
+
return (relationGraph?.relations ?? [])
|
|
483
|
+
.filter((relation) => relation.entryId === entry.id || entryNodeIds.has(relation.from) || entryNodeIds.has(relation.to))
|
|
484
|
+
.map(({ id }) => id)
|
|
485
|
+
.sort(compareStableText);
|
|
486
|
+
}
|
|
487
|
+
/** @lang zh-CN 构造含 profile linkage 的 body-free renderer manifest。 @lang en Builds a body-free renderer manifest with presentation-profile linkage. */
|
|
488
|
+
function createProjectManifest(projectInput, files, pageTitle, options, navigationIndex, presentationBundle, portalContext) {
|
|
143
489
|
const projectId = projectInput.project.id ?? `project:${projectInput.project.name}`;
|
|
144
490
|
const views = collectProjectViews(projectInput.entries);
|
|
145
491
|
const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
|
|
@@ -161,6 +507,9 @@ function createProjectManifest(projectInput, files, pageTitle, options, navigati
|
|
|
161
507
|
name: projectInput.project.name,
|
|
162
508
|
views,
|
|
163
509
|
entryCounts: countEntriesByView(projectInput.entries),
|
|
510
|
+
theme: getDefaultDocumentationPortalThemeReference(),
|
|
511
|
+
presentationProfile: createProjectPresentationProfileRef(presentationBundle),
|
|
512
|
+
...(projectInput.project.productVersion ? { productVersion: projectInput.project.productVersion } : {}),
|
|
164
513
|
navigationIndex: {
|
|
165
514
|
contract: navigationIndex.contract,
|
|
166
515
|
contractVersion: navigationIndex.contractVersion,
|
|
@@ -169,6 +518,23 @@ function createProjectManifest(projectInput, files, pageTitle, options, navigati
|
|
|
169
518
|
},
|
|
170
519
|
...(projectInput.profiles && projectInput.profiles.length > 0 ? { profiles: projectInput.profiles } : {}),
|
|
171
520
|
...(projectInput.docSourceMaps && projectInput.docSourceMaps.length > 0 ? { docSourceMaps: projectInput.docSourceMaps } : {}),
|
|
521
|
+
...(projectInput.generatedDocumentationBindingProjection
|
|
522
|
+
? {
|
|
523
|
+
generatedDocumentationBindingProjection: {
|
|
524
|
+
bindingCount: projectInput.generatedDocumentationBindingProjection.summary.bindingCount,
|
|
525
|
+
contract: projectInput.generatedDocumentationBindingProjection.contract,
|
|
526
|
+
contractVersion: projectInput.generatedDocumentationBindingProjection.contractVersion,
|
|
527
|
+
path: "project-index.json",
|
|
528
|
+
status: projectInput.generatedDocumentationBindingProjection.status,
|
|
529
|
+
targetCount: projectInput.generatedDocumentationBindingProjection.summary.targetCount
|
|
530
|
+
}
|
|
531
|
+
}
|
|
532
|
+
: {}),
|
|
533
|
+
...(projectInput.businessFlowDocumentationProjection
|
|
534
|
+
? {
|
|
535
|
+
businessFlowDocumentationProjection: createProjectBusinessFlowProjectionRef(projectInput.businessFlowDocumentationProjection)
|
|
536
|
+
}
|
|
537
|
+
: {}),
|
|
172
538
|
...(projectInput.relationGraph && projectInput.relationGraph.relationCount > 0
|
|
173
539
|
? {
|
|
174
540
|
relationGraph: {
|
|
@@ -179,11 +545,18 @@ function createProjectManifest(projectInput, files, pageTitle, options, navigati
|
|
|
179
545
|
path: "project-index.json"
|
|
180
546
|
}
|
|
181
547
|
}
|
|
548
|
+
: {}),
|
|
549
|
+
...(navigationIndex.site?.informationArchitecture
|
|
550
|
+
? { informationArchitecture: navigationIndex.site.informationArchitecture }
|
|
551
|
+
: {}),
|
|
552
|
+
...(portalContext.uiLocaleAdoption
|
|
553
|
+
? { uiLocaleCompleteness: createProjectUiLocaleCompletenessRef(portalContext.uiLocaleAdoption) }
|
|
182
554
|
: {})
|
|
183
555
|
}
|
|
184
556
|
};
|
|
185
557
|
}
|
|
186
|
-
|
|
558
|
+
/** @lang zh-CN 构造 owner route index,并附加 neutral topic/page/fragment identity 和 profile 引用。 @lang en Builds the owner route index with neutral topic/page/fragment identities and a profile reference. */
|
|
559
|
+
function createProjectNavigationIndex(projectInput, pageTitle, options, portalContext, presentationBundle) {
|
|
187
560
|
const projectId = projectInput.project.id ?? `project:${projectInput.project.name}`;
|
|
188
561
|
const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
|
|
189
562
|
return {
|
|
@@ -196,7 +569,8 @@ function createProjectNavigationIndex(projectInput, pageTitle, options) {
|
|
|
196
569
|
locales: localeModel.locales,
|
|
197
570
|
name: projectInput.project.name,
|
|
198
571
|
title: pageTitle,
|
|
199
|
-
views: collectProjectViews(projectInput.entries)
|
|
572
|
+
views: collectProjectViews(projectInput.entries),
|
|
573
|
+
...(projectInput.project.productVersion ? { productVersion: projectInput.project.productVersion } : {})
|
|
200
574
|
},
|
|
201
575
|
entries: projectInput.entries
|
|
202
576
|
.map((entry) => ({
|
|
@@ -210,24 +584,67 @@ function createProjectNavigationIndex(projectInput, pageTitle, options) {
|
|
|
210
584
|
...(entry.profile ? { profile: entry.profile } : {}),
|
|
211
585
|
...(entry.input ? { input: entry.input } : {}),
|
|
212
586
|
...(entry.source ? { source: omitProjectSourcePreview(entry.source) } : {}),
|
|
587
|
+
...(entry.sourceUsability ? { sourceUsability: selectProjectSourceUsability(entry.sourceUsability) } : {}),
|
|
588
|
+
...(entry.sourceCommentProjection && portalContext.sourceCommentProjection
|
|
589
|
+
? { sourceCommentProjection: selectProjectSourceCommentProjection(entry.sourceCommentProjection) }
|
|
590
|
+
: {}),
|
|
213
591
|
...(entry.symbolId ? { symbolId: entry.symbolId } : {}),
|
|
214
592
|
...(entry.hierarchy ? { hierarchy: entry.hierarchy } : {}),
|
|
215
593
|
contentPath: createProjectEntryContentPath(entry.id),
|
|
216
|
-
...(
|
|
594
|
+
...(options.projectSite?.layout === "single-page" ? {} : { noScriptPagePath: createProjectNoScriptPagePath(entry.id) }),
|
|
595
|
+
...(portalContext.uiLocaleAdoption && options.projectSite?.layout !== "single-page"
|
|
596
|
+
? {
|
|
597
|
+
noScriptLocalePages: DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES.map((uiLocale) => ({
|
|
598
|
+
uiLocale,
|
|
599
|
+
path: createProjectLocalizedNoScriptPagePath(entry.id, uiLocale)
|
|
600
|
+
}))
|
|
601
|
+
}
|
|
602
|
+
: {}),
|
|
603
|
+
...(portalContext.informationArchitecture
|
|
604
|
+
? {
|
|
605
|
+
presentationPath: createProjectEntryPresentationPath(entry, projectInput.entries, portalContext.informationArchitecture),
|
|
606
|
+
memberAnchor: entry.id,
|
|
607
|
+
...(entry.semanticPath ? { semanticPath: entry.semanticPath } : {})
|
|
608
|
+
}
|
|
609
|
+
: {}),
|
|
610
|
+
...(entry.docSourceMap ? { docSourceMap: entry.docSourceMap } : {}),
|
|
611
|
+
...(presentationBundle.topicByEntryId.get(entry.id)
|
|
612
|
+
? {
|
|
613
|
+
presentationTopicId: presentationBundle.topicByEntryId.get(entry.id).topicId,
|
|
614
|
+
presentationPageId: presentationBundle.topicByEntryId.get(entry.id).pageId,
|
|
615
|
+
presentationFragmentId: presentationBundle.topicByEntryId.get(entry.id).fragmentId
|
|
616
|
+
}
|
|
617
|
+
: {})
|
|
217
618
|
}))
|
|
218
619
|
.sort(compareProjectNavigationEntries),
|
|
219
620
|
groups: collectProjectNavigationGroups(projectInput.entries),
|
|
220
|
-
navigationTree: collectProjectNavigationTree(projectInput.entries),
|
|
621
|
+
navigationTree: applyProjectNavigationPresentationPaths(collectProjectNavigationTree(projectInput.entries, portalContext.informationArchitecture), projectInput.entries, portalContext.informationArchitecture),
|
|
221
622
|
profiles: [...(projectInput.profiles ?? [])].sort(compareProjectProfiles),
|
|
222
623
|
docSourceMaps: [...(projectInput.docSourceMaps ?? [])].sort(compareProjectDocSourceMaps),
|
|
624
|
+
...(projectInput.generatedDocumentationBindingProjection
|
|
625
|
+
? { generatedDocumentationBindingProjection: projectInput.generatedDocumentationBindingProjection }
|
|
626
|
+
: {}),
|
|
627
|
+
...(projectInput.documentationContinuity ? { documentationContinuity: projectInput.documentationContinuity } : {}),
|
|
628
|
+
...(projectInput.ownerAdoption ? { ownerAdoption: projectInput.ownerAdoption } : {}),
|
|
629
|
+
...(projectInput.businessFlowDocumentationProjection
|
|
630
|
+
? { businessFlowDocumentationProjection: projectInput.businessFlowDocumentationProjection }
|
|
631
|
+
: {}),
|
|
223
632
|
site: {
|
|
224
633
|
layout: options.projectSite?.layout ?? "split-site",
|
|
634
|
+
theme: getDefaultDocumentationPortalThemeReference(),
|
|
635
|
+
presentationProfile: createProjectPresentationProfileRef(presentationBundle),
|
|
225
636
|
...(options.projectSite?.layout === "single-page" ? {} : {
|
|
226
637
|
navigationRootPath: "navigation/root.json",
|
|
227
638
|
searchIndexPath: "search/index.json",
|
|
228
639
|
relationIndexPath: "relations/project.json"
|
|
229
640
|
}),
|
|
230
|
-
sourcePresentation: options.projectSite?.source?.presentation ?? "
|
|
641
|
+
sourcePresentation: options.projectSite?.source?.presentation ?? "fetch",
|
|
642
|
+
...(portalContext.informationArchitecture
|
|
643
|
+
? { informationArchitecture: portalContext.informationArchitecture }
|
|
644
|
+
: {}),
|
|
645
|
+
...(portalContext.uiLocaleAdoption
|
|
646
|
+
? { uiLocaleCompleteness: createProjectUiLocaleCompletenessRef(portalContext.uiLocaleAdoption) }
|
|
647
|
+
: {})
|
|
231
648
|
},
|
|
232
649
|
...(projectInput.relationGraph && projectInput.relationGraph.relationCount > 0
|
|
233
650
|
? { relationGraph: projectInput.relationGraph }
|
|
@@ -235,19 +652,20 @@ function createProjectNavigationIndex(projectInput, pageTitle, options) {
|
|
|
235
652
|
};
|
|
236
653
|
}
|
|
237
654
|
/**
|
|
238
|
-
* 生成大型项目默认使用的 split-site
|
|
239
|
-
* Generates the split-site file set
|
|
655
|
+
* @lang zh-CN 生成大型项目默认使用的 split-site 文件集合;入口页只保留应用壳,entry/source 正文保持分离。
|
|
656
|
+
* @lang en Generates the default split-site file set for large projects; the entry page retains only the shell while entry/source bodies remain separate.
|
|
240
657
|
*/
|
|
241
|
-
function createProjectSplitSiteFiles(pageTitle, projectInput, navigationIndex, options) {
|
|
658
|
+
function createProjectSplitSiteFiles(pageTitle, projectInput, navigationIndex, options, portalContext) {
|
|
242
659
|
const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
|
|
660
|
+
const informationArchitecture = portalContext.informationArchitecture;
|
|
243
661
|
const files = [
|
|
244
662
|
{
|
|
245
663
|
path: "index.html",
|
|
246
|
-
contents: renderProjectSplitSiteHtml(pageTitle, projectInput, options),
|
|
664
|
+
contents: renderProjectSplitSiteHtml(pageTitle, projectInput, options, portalContext),
|
|
247
665
|
contentType: "text/html; charset=utf-8",
|
|
248
666
|
role: "entry"
|
|
249
667
|
},
|
|
250
|
-
...createProjectNavigationShardFiles(navigationIndex.navigationTree),
|
|
668
|
+
...createProjectNavigationShardFiles(navigationIndex.navigationTree, informationArchitecture?.loadingStrategy ?? "lazy"),
|
|
251
669
|
{
|
|
252
670
|
path: "search/index.json",
|
|
253
671
|
contents: `${JSON.stringify({
|
|
@@ -259,6 +677,13 @@ function createProjectSplitSiteFiles(pageTitle, projectInput, navigationIndex, o
|
|
|
259
677
|
kind: entry.kind,
|
|
260
678
|
view: entry.view,
|
|
261
679
|
contentPath: createProjectEntryContentPath(entry.id),
|
|
680
|
+
noScriptPagePath: createProjectNoScriptPagePath(entry.id),
|
|
681
|
+
...(informationArchitecture
|
|
682
|
+
? {
|
|
683
|
+
presentationPath: createProjectEntryPresentationPath(entry, projectInput.entries, informationArchitecture),
|
|
684
|
+
memberAnchor: entry.id
|
|
685
|
+
}
|
|
686
|
+
: {}),
|
|
262
687
|
searchText: createProjectEntrySearchText(entry)
|
|
263
688
|
}))
|
|
264
689
|
}, null, 2)}\n`,
|
|
@@ -272,19 +697,104 @@ function createProjectSplitSiteFiles(pageTitle, projectInput, navigationIndex, o
|
|
|
272
697
|
role: "index"
|
|
273
698
|
}
|
|
274
699
|
];
|
|
700
|
+
// <lang><zh-CN>no-script 入口与逐 topic 页面保持独立,不把数千节点重新塞回应用壳。</zh-CN><en>The no-script index and per-topic pages stay separate so thousands of nodes are not embedded back into the application shell.</en></lang>
|
|
701
|
+
const noScriptProjectInput = createProjectNoScriptProjectInput(projectInput);
|
|
702
|
+
// <lang><zh-CN>按稳定 entry id 建立单次索引,避免大型项目为每页线性扫描全部节点。</zh-CN><en>Build a one-time stable-entry index so large projects do not scan every node for every page.</en></lang>
|
|
703
|
+
const noScriptEntryById = new Map(noScriptProjectInput.entries.map((entry) => [entry.id, entry]));
|
|
704
|
+
files.push({
|
|
705
|
+
path: "pages/index.html",
|
|
706
|
+
contents: renderProjectNoScriptIndexHtml(pageTitle, noScriptProjectInput, localeModel.selectedLocale, portalContext),
|
|
707
|
+
contentType: "text/html; charset=utf-8",
|
|
708
|
+
role: "entry"
|
|
709
|
+
});
|
|
710
|
+
// <lang><zh-CN>采用 W-P123 的 surface 为每个 UI locale 生成真实静态入口;legacy 默认路径仍保留。</zh-CN><en>A W-P123-adopted surface emits a real static entry for every UI locale while retaining the legacy default path.</en></lang>
|
|
711
|
+
if (portalContext.uiLocaleAdoption) {
|
|
712
|
+
for (const uiLocale of DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES) {
|
|
713
|
+
const localizedContext = withProjectUiLocale(portalContext, uiLocale);
|
|
714
|
+
files.push({
|
|
715
|
+
path: `pages/${uiLocale}/index.html`,
|
|
716
|
+
contents: renderProjectNoScriptIndexHtml(pageTitle, noScriptProjectInput, localeModel.selectedLocale, localizedContext, true),
|
|
717
|
+
contentType: "text/html; charset=utf-8",
|
|
718
|
+
role: "entry"
|
|
719
|
+
});
|
|
720
|
+
}
|
|
721
|
+
}
|
|
722
|
+
// <lang zh-CN>canonical entry fragment 始终生成,保证旧 deep link 与不识别 IA 的 consumer 可回退。</lang>
|
|
723
|
+
// <lang en>Canonical entry fragments are always emitted so old deep links and IA-unaware consumers retain a fallback.</lang>
|
|
275
724
|
for (const entry of projectInput.entries) {
|
|
725
|
+
// <lang><zh-CN>索引与原输入由同一次确定性映射产生,因此对应 no-script entry 必须存在。</zh-CN><en>The index and original input come from the same deterministic mapping, so the matching no-script entry must exist.</en></lang>
|
|
726
|
+
const noScriptEntry = noScriptEntryById.get(entry.id);
|
|
727
|
+
if (!noScriptEntry) {
|
|
728
|
+
throw new Error(`HIA_RENDERER_NO_SCRIPT_ENTRY_MISSING: ${entry.id}`);
|
|
729
|
+
}
|
|
276
730
|
files.push({
|
|
277
731
|
path: createProjectEntryContentPath(entry.id),
|
|
278
|
-
contents:
|
|
732
|
+
contents: informationArchitecture
|
|
733
|
+
? renderProjectSemanticTopic(entry, projectInput, localeModel.locales, localeModel.selectedLocale, portalContext, informationArchitecture.memberPlacement === "with-parent")
|
|
734
|
+
: renderProjectEntry(entry, localeModel.locales, localeModel.selectedLocale),
|
|
279
735
|
contentType: "text/html; charset=utf-8",
|
|
280
736
|
role: "asset"
|
|
281
737
|
});
|
|
738
|
+
files.push({
|
|
739
|
+
path: createProjectNoScriptPagePath(entry.id),
|
|
740
|
+
contents: renderProjectNoScriptEntryHtml(pageTitle, noScriptEntry, noScriptProjectInput, localeModel, portalContext),
|
|
741
|
+
contentType: "text/html; charset=utf-8",
|
|
742
|
+
role: "entry"
|
|
743
|
+
});
|
|
744
|
+
if (portalContext.uiLocaleAdoption) {
|
|
745
|
+
for (const uiLocale of DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES) {
|
|
746
|
+
const localizedContext = withProjectUiLocale(portalContext, uiLocale);
|
|
747
|
+
files.push({
|
|
748
|
+
path: createProjectLocalizedNoScriptPagePath(entry.id, uiLocale),
|
|
749
|
+
contents: renderProjectNoScriptEntryHtml(pageTitle, noScriptEntry, noScriptProjectInput, localeModel, localizedContext, true),
|
|
750
|
+
contentType: "text/html; charset=utf-8",
|
|
751
|
+
role: "entry"
|
|
752
|
+
});
|
|
753
|
+
}
|
|
754
|
+
}
|
|
755
|
+
}
|
|
756
|
+
// <lang zh-CN>semantic-container 只增加 presentation fragment,不替换 canonical fragment。</lang>
|
|
757
|
+
// <lang en>Semantic containers add presentation fragments without replacing canonical fragments.</lang>
|
|
758
|
+
if (informationArchitecture?.contentGrouping === "semantic-container") {
|
|
759
|
+
files.push(...createProjectSemanticContainerFiles(projectInput, localeModel, portalContext));
|
|
760
|
+
}
|
|
761
|
+
// <lang zh-CN>eager 以单一 index 预载 presentation fragment;canonical files 仍保持独立可寻址。</lang>
|
|
762
|
+
// <lang en>Eager delivery preloads presentation fragments through one index while canonical files remain independently addressable.</lang>
|
|
763
|
+
if (informationArchitecture?.loadingStrategy === "eager") {
|
|
764
|
+
const presentationPaths = new Set(navigationIndex.entries.map((entry) => entry.presentationPath ?? entry.contentPath).filter((path) => Boolean(path)));
|
|
765
|
+
const fragments = files
|
|
766
|
+
.filter((file) => presentationPaths.has(file.path))
|
|
767
|
+
.map((file) => ({ path: file.path, contents: file.contents }))
|
|
768
|
+
.sort((left, right) => compareStableText(left.path, right.path));
|
|
769
|
+
files.push({
|
|
770
|
+
path: "content/eager.json",
|
|
771
|
+
contents: `${JSON.stringify({
|
|
772
|
+
contract: "documentation-portal-eager-fragment-index",
|
|
773
|
+
contractVersion: "0.1.0-draft",
|
|
774
|
+
fragments
|
|
775
|
+
}, null, 2)}\n`,
|
|
776
|
+
contentType: "application/json; charset=utf-8",
|
|
777
|
+
role: "index"
|
|
778
|
+
});
|
|
282
779
|
}
|
|
283
780
|
return files;
|
|
284
781
|
}
|
|
285
|
-
function createProjectNavigationShardFiles(nodes) {
|
|
782
|
+
function createProjectNavigationShardFiles(nodes, loadingStrategy) {
|
|
286
783
|
const files = [];
|
|
287
784
|
const emittedPaths = new Set();
|
|
785
|
+
if (loadingStrategy === "eager") {
|
|
786
|
+
return [{
|
|
787
|
+
path: "navigation/root.json",
|
|
788
|
+
contents: `${JSON.stringify({
|
|
789
|
+
contract: "hia-project-navigation-shard",
|
|
790
|
+
contractVersion: "0.1.0-draft",
|
|
791
|
+
nodeId: "root",
|
|
792
|
+
children: nodes
|
|
793
|
+
}, null, 2)}\n`,
|
|
794
|
+
contentType: "application/json; charset=utf-8",
|
|
795
|
+
role: "index"
|
|
796
|
+
}];
|
|
797
|
+
}
|
|
288
798
|
const emitChildren = (nodeId, children, root = false) => {
|
|
289
799
|
const shardPath = root ? "navigation/root.json" : createProjectNavigationChildrenPath(nodeId);
|
|
290
800
|
if (emittedPaths.has(shardPath)) {
|
|
@@ -318,12 +828,104 @@ function toLazyProjectNavigationNode(node) {
|
|
|
318
828
|
...(node.children && node.children.length > 0
|
|
319
829
|
? { childrenPath: createProjectNavigationChildrenPath(node.id) }
|
|
320
830
|
: {}),
|
|
321
|
-
...(node.entryId ? { contentPath: createProjectEntryContentPath(node.entryId) } : {})
|
|
831
|
+
...(node.entryId && !node.contentPath ? { contentPath: createProjectEntryContentPath(node.entryId) } : {})
|
|
322
832
|
};
|
|
323
833
|
}
|
|
324
834
|
function createProjectEntryContentPath(entryId) {
|
|
325
835
|
return `entries/${stableProjectArtifactName(entryId)}.html`;
|
|
326
836
|
}
|
|
837
|
+
/** @lang zh-CN 为每个 neutral topic 生成稳定的 no-script owner page route。 @lang en Generates a stable no-script owner page route for every neutral topic. */
|
|
838
|
+
function createProjectNoScriptPagePath(entryId) {
|
|
839
|
+
return `pages/${stableProjectArtifactName(entryId)}.html`;
|
|
840
|
+
}
|
|
841
|
+
/**
|
|
842
|
+
* @lang zh-CN 为一个 UI locale 生成可直接访问的无脚本 owner page route。
|
|
843
|
+
* @lang en Generates a directly addressable no-script owner-page route for one UI locale.
|
|
844
|
+
*/
|
|
845
|
+
function createProjectLocalizedNoScriptPagePath(entryId, uiLocale) {
|
|
846
|
+
return `pages/${uiLocale}/${stableProjectArtifactName(entryId)}.html`;
|
|
847
|
+
}
|
|
848
|
+
/**
|
|
849
|
+
* 计算 additive presentation location;canonical contentPath 永远由 entry id 单独计算。
|
|
850
|
+
* Computes the additive presentation location; canonical contentPath is always computed independently from the entry id.
|
|
851
|
+
*/
|
|
852
|
+
function createProjectEntryPresentationPath(entry, entries, informationArchitecture) {
|
|
853
|
+
const presentationOwner = informationArchitecture.memberPlacement === "with-parent"
|
|
854
|
+
? findProjectParentEntry(entry, entries) ?? entry
|
|
855
|
+
: entry;
|
|
856
|
+
if (informationArchitecture.contentGrouping === "semantic-container") {
|
|
857
|
+
return createProjectSemanticContainerPath(presentationOwner);
|
|
858
|
+
}
|
|
859
|
+
return createProjectEntryContentPath(presentationOwner.id);
|
|
860
|
+
}
|
|
861
|
+
/** semantic container id 只消费 manifest segment 或稳定 unscoped view,不读取 source path。Semantic container ids use manifest segments or a stable unscoped view, never source paths. */
|
|
862
|
+
function createProjectSemanticContainerPath(entry) {
|
|
863
|
+
const identity = entry.semanticPath && entry.semanticPath.length > 0
|
|
864
|
+
? entry.semanticPath.map((segment) => `${segment.kind}:${segment.id}`).join("|")
|
|
865
|
+
: `unscoped:${entry.view}`;
|
|
866
|
+
return `semantic-containers/${stableProjectArtifactName(identity)}.html`;
|
|
867
|
+
}
|
|
868
|
+
/** 仅按显式 parentSymbolId/symbolId 解析父入口,不执行名称或路径猜测。Resolves a parent only by explicit parentSymbolId/symbolId, with no name or path inference. */
|
|
869
|
+
function findProjectParentEntry(entry, entries) {
|
|
870
|
+
const parentSymbolId = entry.hierarchy?.parentSymbolId;
|
|
871
|
+
return parentSymbolId ? entries.find((candidate) => candidate.symbolId === parentSymbolId) : undefined;
|
|
872
|
+
}
|
|
873
|
+
/** 把 canonical 与 presentation location 投影到 leaf node,保持 tree node identity 不变。Projects canonical and presentation locations onto leaf nodes without changing tree-node identity. */
|
|
874
|
+
function applyProjectNavigationPresentationPaths(nodes, entries, informationArchitecture) {
|
|
875
|
+
const entriesById = new Map(entries.map((entry) => [entry.id, entry]));
|
|
876
|
+
return nodes.map((node) => {
|
|
877
|
+
const entry = node.entryId ? entriesById.get(node.entryId) : undefined;
|
|
878
|
+
return {
|
|
879
|
+
...node,
|
|
880
|
+
...(node.children
|
|
881
|
+
? { children: applyProjectNavigationPresentationPaths(node.children, entries, informationArchitecture) }
|
|
882
|
+
: {}),
|
|
883
|
+
...(entry ? { contentPath: createProjectEntryContentPath(entry.id) } : {}),
|
|
884
|
+
...(entry && informationArchitecture
|
|
885
|
+
? {
|
|
886
|
+
presentationPath: createProjectEntryPresentationPath(entry, entries, informationArchitecture),
|
|
887
|
+
memberAnchor: entry.id
|
|
888
|
+
}
|
|
889
|
+
: {})
|
|
890
|
+
};
|
|
891
|
+
});
|
|
892
|
+
}
|
|
893
|
+
/**
|
|
894
|
+
* 按 presentation path 生成 container fragment;with-parent child 由 parent topic 的 members section 承载。
|
|
895
|
+
* Emits container fragments by presentation path; with-parent children are carried by the parent topic's members section.
|
|
896
|
+
*/
|
|
897
|
+
function createProjectSemanticContainerFiles(projectInput, localeModel, portalContext) {
|
|
898
|
+
const informationArchitecture = portalContext.informationArchitecture;
|
|
899
|
+
if (!informationArchitecture) {
|
|
900
|
+
return [];
|
|
901
|
+
}
|
|
902
|
+
const groups = new Map();
|
|
903
|
+
for (const entry of projectInput.entries) {
|
|
904
|
+
const path = createProjectEntryPresentationPath(entry, projectInput.entries, informationArchitecture);
|
|
905
|
+
const bucket = groups.get(path) ?? [];
|
|
906
|
+
bucket.push(entry);
|
|
907
|
+
groups.set(path, bucket);
|
|
908
|
+
}
|
|
909
|
+
return [...groups.entries()]
|
|
910
|
+
.sort(([left], [right]) => compareStableText(left, right))
|
|
911
|
+
.map(([path, entries]) => {
|
|
912
|
+
const visibleEntries = informationArchitecture.memberPlacement === "with-parent"
|
|
913
|
+
? entries.filter((entry) => {
|
|
914
|
+
const parent = findProjectParentEntry(entry, projectInput.entries);
|
|
915
|
+
return !parent || createProjectEntryPresentationPath(parent, projectInput.entries, informationArchitecture) !== path;
|
|
916
|
+
})
|
|
917
|
+
: entries;
|
|
918
|
+
return {
|
|
919
|
+
path,
|
|
920
|
+
contents: visibleEntries
|
|
921
|
+
.sort(compareProjectNavigationEntries)
|
|
922
|
+
.map((entry) => renderProjectSemanticTopic(entry, projectInput, localeModel.locales, localeModel.selectedLocale, portalContext, informationArchitecture.memberPlacement === "with-parent"))
|
|
923
|
+
.join(""),
|
|
924
|
+
contentType: "text/html; charset=utf-8",
|
|
925
|
+
role: "asset"
|
|
926
|
+
};
|
|
927
|
+
});
|
|
928
|
+
}
|
|
327
929
|
function createProjectNavigationChildrenPath(nodeId) {
|
|
328
930
|
return `navigation/${stableProjectArtifactName(nodeId)}.json`;
|
|
329
931
|
}
|
|
@@ -352,6 +954,39 @@ function compareProjectDocSourceMaps(left, right) {
|
|
|
352
954
|
function compareStableText(left, right) {
|
|
353
955
|
return left < right ? -1 : left > right ? 1 : 0;
|
|
354
956
|
}
|
|
957
|
+
/**
|
|
958
|
+
* @lang zh-CN 生成无脚本也可读取的 theme root metadata;字段只来自内置 exact reference。
|
|
959
|
+
* @lang en Renders theme-root metadata readable without scripts; every field comes from the built-in exact reference.
|
|
960
|
+
*
|
|
961
|
+
* @param themeSelection - 可选的 Portal-owned build-time 默认 skin/scheme。Optional Portal-owned build-time default skin/scheme.
|
|
962
|
+
* @returns 适用于 `<html>` opening tag 的 escaped attributes。Escaped attributes for an opening `<html>` tag.
|
|
963
|
+
*/
|
|
964
|
+
function renderDefaultThemeRootAttributes(themeSelection) {
|
|
965
|
+
// <lang><zh-CN>每次取得新 reference,避免 renderer 修改 theme owner 的共享对象。</zh-CN><en>Obtain a fresh reference each time so the renderer cannot mutate the theme owner's shared object.</en></lang>
|
|
966
|
+
const theme = getDefaultDocumentationPortalThemeReference();
|
|
967
|
+
return [
|
|
968
|
+
`data-hia-theme="${escapeHtml(theme.name)}"`,
|
|
969
|
+
`data-hia-theme-contract="${escapeHtml(theme.contract)}"`,
|
|
970
|
+
`data-hia-theme-contract-version="${escapeHtml(theme.contractVersion)}"`,
|
|
971
|
+
`data-hia-theme-color-scheme-policy="${escapeHtml(theme.colorSchemePolicy)}"`,
|
|
972
|
+
`data-hia-theme-disclosure="${escapeHtml(theme.disclosure)}"`,
|
|
973
|
+
...(themeSelection
|
|
974
|
+
? [
|
|
975
|
+
`data-hia-skin="${escapeHtml(themeSelection.skinId)}"`,
|
|
976
|
+
`data-hia-scheme="${escapeHtml(themeSelection.scheme)}"`
|
|
977
|
+
]
|
|
978
|
+
: [])
|
|
979
|
+
].join(" ");
|
|
980
|
+
}
|
|
981
|
+
/** @lang zh-CN 优先共用theme,逐项回退旧项目theme与默认值;未知选择在产生HTML前拒绝。 @lang en Prefers shared theme, falls back per field to legacy project theme and defaults, and rejects unknown selections before HTML generation. */
|
|
982
|
+
function resolveThemeSelection(options) {
|
|
983
|
+
// <lang><zh-CN>皮肤与配色独立解析,不从品牌颜色推断另一种主题。</zh-CN><en>Resolve skin and scheme independently without inferring another theme from brand colors.</en></lang>
|
|
984
|
+
const skinId = options.theme?.skinId ?? options.projectSite?.theme?.skinId ?? "portal.classic";
|
|
985
|
+
const scheme = options.theme?.scheme ?? options.projectSite?.theme?.scheme ?? "system";
|
|
986
|
+
if (!PORTAL_THEME_SKIN_IDS.includes(skinId) || !PORTAL_THEME_SCHEMES.includes(scheme))
|
|
987
|
+
throw new TypeError("HIA_PORTAL_THEME_SELECTION_INVALID: Portal skin and scheme must use the built-in closed catalog.");
|
|
988
|
+
return { skinId, scheme };
|
|
989
|
+
}
|
|
355
990
|
function renderIndexHtml(pageTitle, document, options) {
|
|
356
991
|
const selectedLocale = options.locale || document.defaultLocale;
|
|
357
992
|
const locales = normalizeLocales(document, selectedLocale);
|
|
@@ -361,7 +996,7 @@ function renderIndexHtml(pageTitle, document, options) {
|
|
|
361
996
|
const symbols = document.symbols.map((symbol) => renderSymbol(symbol, document, locales, selectedLocale)).join("");
|
|
362
997
|
return [
|
|
363
998
|
"<!doctype html>",
|
|
364
|
-
`<html lang="${escapeHtml(selectedLocale)}">`,
|
|
999
|
+
`<html lang="${escapeHtml(selectedLocale)}" ${renderDefaultThemeRootAttributes(resolveThemeSelection(options))}>`,
|
|
365
1000
|
"<head>",
|
|
366
1001
|
"<meta charset=\"utf-8\">",
|
|
367
1002
|
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
|
|
@@ -385,36 +1020,91 @@ function renderIndexHtml(pageTitle, document, options) {
|
|
|
385
1020
|
"</html>"
|
|
386
1021
|
].join("");
|
|
387
1022
|
}
|
|
388
|
-
|
|
1023
|
+
/**
|
|
1024
|
+
* @lang zh-CN
|
|
1025
|
+
* 渲染一个带稳定 identity 的 UI 文本节点;译文先按纯文本解析,再进行 HTML 转义。
|
|
1026
|
+
*
|
|
1027
|
+
* @lang en
|
|
1028
|
+
* Renders a UI text node with a stable identity; translation is resolved as plain text before HTML escaping.
|
|
1029
|
+
*/
|
|
1030
|
+
function renderProjectUiMessage(portalContext, messageId, values = {}, fallback = "") {
|
|
1031
|
+
if (!portalContext.uiLocaleAdoption) {
|
|
1032
|
+
return escapeHtml(fallback);
|
|
1033
|
+
}
|
|
1034
|
+
const valueAttribute = Object.keys(values).length > 0
|
|
1035
|
+
? ` data-hia-ui-values="${escapeHtml(JSON.stringify(values))}"`
|
|
1036
|
+
: "";
|
|
1037
|
+
const text = resolveDocumentationPortalUiMessage(portalContext.uiLocaleAdoption, portalContext.uiLocale, messageId, values);
|
|
1038
|
+
return `<span data-hia-ui-message="${escapeHtml(messageId)}"${valueAttribute}>${escapeHtml(text)}</span>`;
|
|
1039
|
+
}
|
|
1040
|
+
/** @lang zh-CN 解析 attribute/dynamic state 使用的 UI 纯文本,并为 legacy surface 保留既有 fallback。 @lang en Resolves UI plain text for attributes/dynamic state while retaining the existing fallback for legacy surfaces. */
|
|
1041
|
+
function resolveProjectUiPlainText(portalContext, messageId, values = {}, fallback = "") {
|
|
1042
|
+
return portalContext.uiLocaleAdoption
|
|
1043
|
+
? resolveDocumentationPortalUiMessage(portalContext.uiLocaleAdoption, portalContext.uiLocale, messageId, values)
|
|
1044
|
+
: fallback;
|
|
1045
|
+
}
|
|
1046
|
+
/** @lang zh-CN 为共享 legacy/adopted renderer helper 选择带 marker 的消息或原有文本。 @lang en Selects a marked message or original text for renderer helpers shared by legacy and adopted surfaces. */
|
|
1047
|
+
function renderOptionalProjectUiMessage(portalContext, messageId, fallback, values = {}) {
|
|
1048
|
+
return portalContext
|
|
1049
|
+
? renderProjectUiMessage(portalContext, messageId, values, fallback)
|
|
1050
|
+
: escapeHtml(fallback);
|
|
1051
|
+
}
|
|
1052
|
+
/**
|
|
1053
|
+
* @lang zh-CN
|
|
1054
|
+
* 为不能包裹 span 的元素生成稳定 message marker,并返回已转义文本。
|
|
1055
|
+
*
|
|
1056
|
+
* @lang en
|
|
1057
|
+
* Creates a stable message marker for elements that cannot wrap a span and returns escaped text.
|
|
1058
|
+
*/
|
|
1059
|
+
function renderProjectUiMarkedText(portalContext, messageId, values = {}) {
|
|
1060
|
+
if (!portalContext.uiLocaleAdoption) {
|
|
1061
|
+
return { attributes: "", text: "" };
|
|
1062
|
+
}
|
|
1063
|
+
const valueAttribute = Object.keys(values).length > 0
|
|
1064
|
+
? ` data-hia-ui-values="${escapeHtml(JSON.stringify(values))}"`
|
|
1065
|
+
: "";
|
|
1066
|
+
return {
|
|
1067
|
+
attributes: ` data-hia-ui-message="${escapeHtml(messageId)}"${valueAttribute}`,
|
|
1068
|
+
text: escapeHtml(resolveDocumentationPortalUiMessage(portalContext.uiLocaleAdoption, portalContext.uiLocale, messageId, values))
|
|
1069
|
+
};
|
|
1070
|
+
}
|
|
1071
|
+
/**
|
|
1072
|
+
* @lang zh-CN 复制 context 并只替换显式 UI locale,供 no-script locale 页面复用同一已验证 bundle/report。
|
|
1073
|
+
* @lang en Copies a context while replacing only its explicit UI locale so no-script locale pages reuse one validated bundle/report.
|
|
1074
|
+
*/
|
|
1075
|
+
function withProjectUiLocale(portalContext, uiLocale) {
|
|
1076
|
+
return {
|
|
1077
|
+
...portalContext,
|
|
1078
|
+
uiLocale,
|
|
1079
|
+
labels: getDocumentationPortalLabels(uiLocale)
|
|
1080
|
+
};
|
|
1081
|
+
}
|
|
1082
|
+
/** @lang zh-CN 渲染彼此独立的 UI/content locale 原生控件。 @lang en Renders independent native UI/content-locale controls. */
|
|
1083
|
+
function renderProjectLocaleControls(contentLocales, selectedContentLocale, portalContext) {
|
|
1084
|
+
if (!portalContext.uiLocaleAdoption) {
|
|
1085
|
+
return renderLocaleControl(contentLocales, selectedContentLocale);
|
|
1086
|
+
}
|
|
1087
|
+
const uiOptions = DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES.map((locale) => (`<option value="${escapeHtml(locale)}"${locale === portalContext.uiLocale ? " selected" : ""}>${escapeHtml(locale)}</option>`)).join("");
|
|
1088
|
+
const contentOptions = contentLocales.map((locale) => (`<option value="${escapeHtml(locale)}"${locale === selectedContentLocale ? " selected" : ""}>${escapeHtml(locale)}</option>`)).join("");
|
|
1089
|
+
return [
|
|
1090
|
+
"<div class=\"hia-language-switch hia-project-language-switch\">",
|
|
1091
|
+
`<label for="hia-ui-locale-control">${renderProjectUiMessage(portalContext, "portal.locale.uilabel")}</label>`,
|
|
1092
|
+
`<select id="hia-ui-locale-control" data-hia-ui-locale-control data-hia-ui-aria="portal.locale.uiaccessible" aria-label="${escapeHtml(resolveDocumentationPortalUiMessage(portalContext.uiLocaleAdoption, portalContext.uiLocale, "portal.locale.uiaccessible"))}">${uiOptions}</select>`,
|
|
1093
|
+
`<label for="hia-locale-control">${renderProjectUiMessage(portalContext, "portal.locale.contentlabel")}</label>`,
|
|
1094
|
+
`<select id="hia-locale-control" data-hia-locale-control data-hia-ui-aria="portal.locale.contentaccessible" aria-label="${escapeHtml(resolveDocumentationPortalUiMessage(portalContext.uiLocaleAdoption, portalContext.uiLocale, "portal.locale.contentaccessible"))}">${contentOptions}</select>`,
|
|
1095
|
+
"</div>"
|
|
1096
|
+
].join("");
|
|
1097
|
+
}
|
|
1098
|
+
/** @lang zh-CN 渲染带 no-script theme 默认和可见选择器的 split-site 应用壳。 @lang en Renders the split-site shell with a no-script theme default and visible selectors. */
|
|
1099
|
+
function renderProjectSplitSiteHtml(pageTitle, projectInput, options, portalContext) {
|
|
389
1100
|
const projectName = projectInput.project.title ?? projectInput.project.name;
|
|
390
1101
|
const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
|
|
391
1102
|
const views = collectProjectViews(projectInput.entries);
|
|
392
1103
|
const entryCounts = countEntriesByView(projectInput.entries);
|
|
393
|
-
const
|
|
394
|
-
const labels = selectedChinese
|
|
395
|
-
? {
|
|
396
|
-
hierarchy: "层级导航",
|
|
397
|
-
loading: "正在加载文档导航...",
|
|
398
|
-
open: "打开",
|
|
399
|
-
relations: "项目关系",
|
|
400
|
-
select: "请从左侧层级树选择一个文档节点。",
|
|
401
|
-
search: "搜索",
|
|
402
|
-
searchPlaceholder: "名称、类型、源码或选择器",
|
|
403
|
-
requiresServer: "按需加载站点需要通过 HTTP(S) 提供;请使用本地静态服务器打开该目录。"
|
|
404
|
-
}
|
|
405
|
-
: {
|
|
406
|
-
hierarchy: "Hierarchy",
|
|
407
|
-
loading: "Loading documentation navigation...",
|
|
408
|
-
open: "Open",
|
|
409
|
-
relations: "Project relations",
|
|
410
|
-
select: "Select a documentation node from the hierarchy.",
|
|
411
|
-
search: "Search",
|
|
412
|
-
searchPlaceholder: "Name, kind, source, selector",
|
|
413
|
-
requiresServer: "The lazy site must be served over HTTP(S); open this directory through a local static server."
|
|
414
|
-
};
|
|
1104
|
+
const labels = portalContext.labels;
|
|
415
1105
|
return [
|
|
416
1106
|
"<!doctype html>",
|
|
417
|
-
`<html lang="${escapeHtml(
|
|
1107
|
+
`<html lang="${escapeHtml(portalContext.uiLocale)}" ${renderDefaultThemeRootAttributes(portalContext.theme)}>`,
|
|
418
1108
|
"<head>",
|
|
419
1109
|
"<meta charset=\"utf-8\">",
|
|
420
1110
|
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
|
|
@@ -426,71 +1116,228 @@ function renderProjectSplitSiteHtml(pageTitle, projectInput, options) {
|
|
|
426
1116
|
"<div class=\"hia-shell hia-project-shell hia-project-split-site\">",
|
|
427
1117
|
"<aside class=\"hia-sidebar\">",
|
|
428
1118
|
`<h1>${escapeHtml(projectName)}</h1>`,
|
|
429
|
-
|
|
430
|
-
|
|
1119
|
+
renderProjectLocaleControls(localeModel.locales, localeModel.selectedLocale, portalContext),
|
|
1120
|
+
renderProjectThemeControl(portalContext.theme, portalContext),
|
|
1121
|
+
renderProjectViewControl(views, entryCounts, portalContext),
|
|
1122
|
+
renderProjectGeneratedDocumentationBindingProjection(projectInput.generatedDocumentationBindingProjection, portalContext),
|
|
431
1123
|
[
|
|
432
1124
|
"<label class=\"hia-project-search\">",
|
|
433
|
-
`<span>${
|
|
434
|
-
`<input type="search" data-hia-project-search placeholder="${escapeHtml(labels.searchPlaceholder)}">`,
|
|
1125
|
+
`<span>${renderProjectUiMessage(portalContext, "portal.search.label", {}, labels.search)}</span>`,
|
|
1126
|
+
`<input type="search" data-hia-project-search${portalContext.uiLocaleAdoption ? " data-hia-ui-placeholder=\"portal.search.placeholder\" data-hia-ui-aria=\"portal.search.accessible\"" : ""} placeholder="${escapeHtml(resolveProjectUiPlainText(portalContext, "portal.search.placeholder", {}, labels.searchPlaceholder))}" aria-label="${escapeHtml(resolveProjectUiPlainText(portalContext, "portal.search.accessible", {}, labels.search))}">`,
|
|
435
1127
|
"</label>"
|
|
436
1128
|
].join(""),
|
|
437
|
-
`<section class="hia-project-summary hia-project-hierarchy"><h2>${
|
|
438
|
-
`<button type="button" class="hia-project-secondary-action" data-hia-project-relations>${
|
|
1129
|
+
`<section class="hia-project-summary hia-project-hierarchy"><h2>${renderProjectUiMessage(portalContext, "portal.navigation.hierarchy", {}, labels.hierarchy)}</h2><div data-hia-project-tree><p class="hia-project-loading" role="status">${renderProjectUiMessage(portalContext, "portal.navigation.loading", {}, labels.loading)}</p></div></section>`,
|
|
1130
|
+
`<button type="button" class="hia-project-secondary-action" data-hia-project-relations>${renderProjectUiMessage(portalContext, "portal.navigation.relations", {}, labels.relations)}</button>`,
|
|
439
1131
|
"</aside>",
|
|
440
|
-
`<main class="hia-main hia-project-main" data-hia-project-content><p class="hia-project-empty">${
|
|
1132
|
+
`<main class="hia-main hia-project-main" data-hia-project-content><p class="hia-project-empty">${renderProjectUiMessage(portalContext, "portal.navigation.select", {}, labels.select)}</p><noscript><p class="hia-noscript-notice"><a href="pages/index.html">${renderProjectUiMessage(portalContext, "portal.navigation.noscriptlink", {}, "No-script page index / 无脚本页面索引")}</a></p></noscript></main>`,
|
|
441
1133
|
"</div>",
|
|
442
1134
|
`<script src="${escapeHtml(DEFAULT_THEME_JS_PATH)}"></script>`,
|
|
443
|
-
renderProjectSplitSiteScript(
|
|
1135
|
+
renderProjectSplitSiteScript(portalContext, portalContext.informationArchitecture?.loadingStrategy ?? "lazy"),
|
|
444
1136
|
"</body>",
|
|
445
1137
|
"</html>"
|
|
446
1138
|
].join("");
|
|
447
1139
|
}
|
|
448
1140
|
/**
|
|
449
|
-
*
|
|
1141
|
+
* @lang zh-CN 渲染独立 no-script 多页索引;它不内嵌 topic 正文,也不依赖 dynamic navigation shard。
|
|
1142
|
+
* @lang en Renders the standalone no-script multi-page index without embedding topic bodies or depending on dynamic navigation shards.
|
|
1143
|
+
*/
|
|
1144
|
+
function renderProjectNoScriptIndexHtml(pageTitle, projectInput, selectedContentLocale, portalContext, localizedRoute = false) {
|
|
1145
|
+
const projectName = projectInput.project.title ?? projectInput.project.name;
|
|
1146
|
+
const links = [...projectInput.entries].sort(compareProjectNavigationEntries).map((entry) => {
|
|
1147
|
+
// <lang><zh-CN>page path 是由固定 `pages/` 前缀与 opaque basename 组成,不需要平台路径 API。</zh-CN><en>The page path consists of the fixed `pages/` prefix and an opaque basename, so no platform path API is needed.</en></lang>
|
|
1148
|
+
const relativePage = `./${createProjectNoScriptPagePath(entry.id).slice("pages/".length)}`;
|
|
1149
|
+
return `<li><a href="${escapeHtml(relativePage)}">${escapeHtml(entry.name)}</a> <small>${escapeHtml(entry.kind)} / ${escapeHtml(formatProjectViewLabel(entry.view))}</small></li>`;
|
|
1150
|
+
}).join("");
|
|
1151
|
+
const documentLocale = portalContext.uiLocaleAdoption ? portalContext.uiLocale : selectedContentLocale;
|
|
1152
|
+
const interactivePath = localizedRoute ? "../../index.html" : "../index.html";
|
|
1153
|
+
const stylesheetPath = localizedRoute ? "../../assets/hia-default.css" : "../assets/hia-default.css";
|
|
1154
|
+
const alternateLinks = portalContext.uiLocaleAdoption
|
|
1155
|
+
? DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES
|
|
1156
|
+
.filter((locale) => locale !== portalContext.uiLocale)
|
|
1157
|
+
.map((locale) => {
|
|
1158
|
+
const path = localizedRoute ? `../${locale}/index.html` : `./${locale}/index.html`;
|
|
1159
|
+
const label = resolveProjectUiPlainText(portalContext, "portal.noscript.localealternate", { locale }, locale);
|
|
1160
|
+
return `<a href="${escapeHtml(path)}" lang="${escapeHtml(locale)}">${escapeHtml(label)}</a>`;
|
|
1161
|
+
})
|
|
1162
|
+
.join(" · ")
|
|
1163
|
+
: "";
|
|
1164
|
+
const skinMessageId = `portal.theme.skin.${portalContext.theme.skinId.slice("portal.".length)}`;
|
|
1165
|
+
const schemeMessageId = `portal.theme.scheme.${portalContext.theme.scheme}`;
|
|
1166
|
+
return [
|
|
1167
|
+
"<!doctype html>",
|
|
1168
|
+
`<html lang="${escapeHtml(documentLocale)}" ${renderDefaultThemeRootAttributes(portalContext.theme)}>`,
|
|
1169
|
+
"<head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
|
|
1170
|
+
`<title>${escapeHtml(pageTitle)} - ${escapeHtml(resolveProjectUiPlainText(portalContext, "portal.noscript.indextitle", {}, "No-script index"))}</title>`,
|
|
1171
|
+
`<link rel="icon" href="data:,"><link rel="stylesheet" href="${escapeHtml(stylesheetPath)}"></head>`,
|
|
1172
|
+
"<body><div class=\"hia-shell hia-project-shell\"><aside class=\"hia-sidebar\">",
|
|
1173
|
+
`<h1>${escapeHtml(projectName)}</h1><p><a href="${escapeHtml(interactivePath)}">${renderProjectUiMessage(portalContext, "portal.noscript.interactive", {}, "Interactive site / 交互站点")}</a></p>`,
|
|
1174
|
+
alternateLinks ? `<p>${alternateLinks}</p>` : "",
|
|
1175
|
+
`<p>${renderProjectUiMessage(portalContext, "portal.theme.skinlabel", {}, "Skin")}:${renderProjectUiMessage(portalContext, skinMessageId, {}, getPortalThemeSkinLabel(portalContext.theme.skinId))} · ${renderProjectUiMessage(portalContext, "portal.theme.schemelabel", {}, "Scheme")}:${renderProjectUiMessage(portalContext, schemeMessageId, {}, getPortalThemeSchemeLabel(portalContext.theme.scheme))}</p>`,
|
|
1176
|
+
`</aside><main class="hia-main hia-project-main"><h2>${renderProjectUiMessage(portalContext, "portal.noscript.pagesheading", {}, "Documentation pages / 文档页面")}</h2>`,
|
|
1177
|
+
`<nav aria-label="${escapeHtml(resolveProjectUiPlainText(portalContext, "portal.noscript.pagesaccessible", {}, "Documentation pages"))}"${portalContext.uiLocaleAdoption ? " data-hia-ui-aria=\"portal.noscript.pagesaccessible\"" : ""}><ul>${links}</ul></nav>`,
|
|
1178
|
+
"</main></div></body></html>"
|
|
1179
|
+
].join("");
|
|
1180
|
+
}
|
|
1181
|
+
/**
|
|
1182
|
+
* @lang zh-CN 渲染一个可直接打开、无脚本仍可使用 native disclosure 阅读的 topic 页面。
|
|
1183
|
+
* @lang en Renders a directly addressable topic page readable through native disclosure without JavaScript.
|
|
1184
|
+
*/
|
|
1185
|
+
function renderProjectNoScriptEntryHtml(pageTitle, entry, projectInput, localeModel, portalContext, localizedRoute = false) {
|
|
1186
|
+
const informationArchitecture = portalContext.informationArchitecture;
|
|
1187
|
+
const article = informationArchitecture
|
|
1188
|
+
? renderProjectSemanticTopic(entry, projectInput, localeModel.locales, localeModel.selectedLocale, portalContext, informationArchitecture.memberPlacement === "with-parent")
|
|
1189
|
+
: renderProjectEntry(entry, localeModel.locales, localeModel.selectedLocale);
|
|
1190
|
+
const documentLocale = portalContext.uiLocaleAdoption ? portalContext.uiLocale : localeModel.selectedLocale;
|
|
1191
|
+
const pageIndexPath = "./index.html";
|
|
1192
|
+
const interactivePath = localizedRoute ? "../../index.html" : "../index.html";
|
|
1193
|
+
const stylesheetPath = localizedRoute ? "../../assets/hia-default.css" : "../assets/hia-default.css";
|
|
1194
|
+
const alternateLinks = portalContext.uiLocaleAdoption
|
|
1195
|
+
? DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES
|
|
1196
|
+
.filter((locale) => locale !== portalContext.uiLocale)
|
|
1197
|
+
.map((locale) => {
|
|
1198
|
+
const path = localizedRoute
|
|
1199
|
+
? `../${locale}/${stableProjectArtifactName(entry.id)}.html`
|
|
1200
|
+
: `./${locale}/${stableProjectArtifactName(entry.id)}.html`;
|
|
1201
|
+
const label = resolveProjectUiPlainText(portalContext, "portal.noscript.localealternate", { locale }, locale);
|
|
1202
|
+
return `<a href="${escapeHtml(path)}" lang="${escapeHtml(locale)}">${escapeHtml(label)}</a>`;
|
|
1203
|
+
})
|
|
1204
|
+
.join(" · ")
|
|
1205
|
+
: "";
|
|
1206
|
+
const skinMessageId = `portal.theme.skin.${portalContext.theme.skinId.slice("portal.".length)}`;
|
|
1207
|
+
const schemeMessageId = `portal.theme.scheme.${portalContext.theme.scheme}`;
|
|
1208
|
+
return [
|
|
1209
|
+
"<!doctype html>",
|
|
1210
|
+
`<html lang="${escapeHtml(documentLocale)}" ${renderDefaultThemeRootAttributes(portalContext.theme)}>`,
|
|
1211
|
+
"<head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
|
|
1212
|
+
`<title>${escapeHtml(entry.name)} - ${escapeHtml(pageTitle)}</title>`,
|
|
1213
|
+
`<link rel="icon" href="data:,"><link rel="stylesheet" href="${escapeHtml(stylesheetPath)}"></head>`,
|
|
1214
|
+
"<body><div class=\"hia-shell hia-project-shell\"><aside class=\"hia-sidebar\">",
|
|
1215
|
+
`<h1>${escapeHtml(projectInput.project.title ?? projectInput.project.name)}</h1>`,
|
|
1216
|
+
`<p><a href="${pageIndexPath}">${renderProjectUiMessage(portalContext, "portal.noscript.pageindex", {}, "Page index / 页面索引")}</a></p><p><a href="${escapeHtml(interactivePath)}">${renderProjectUiMessage(portalContext, "portal.noscript.interactive", {}, "Interactive site / 交互站点")}</a></p>`,
|
|
1217
|
+
alternateLinks ? `<p>${alternateLinks}</p>` : "",
|
|
1218
|
+
`<p>${renderProjectUiMessage(portalContext, "portal.theme.skinlabel", {}, "Skin")}:${renderProjectUiMessage(portalContext, skinMessageId, {}, getPortalThemeSkinLabel(portalContext.theme.skinId))} · ${renderProjectUiMessage(portalContext, "portal.theme.schemelabel", {}, "Scheme")}:${renderProjectUiMessage(portalContext, schemeMessageId, {}, getPortalThemeSchemeLabel(portalContext.theme.scheme))}</p>`,
|
|
1219
|
+
"</aside><main class=\"hia-main hia-project-main\">",
|
|
1220
|
+
article,
|
|
1221
|
+
"</main></div></body></html>"
|
|
1222
|
+
].join("");
|
|
1223
|
+
}
|
|
1224
|
+
/**
|
|
1225
|
+
* @lang zh-CN 生成 split-site 与 single-page 共用的受限 fetch reader;默认展开时加载,也保留显式 manual 模式。
|
|
1226
|
+
* @lang en Generates the constrained fetch reader shared by split-site and single-page output, loading on expansion by default while retaining explicit manual mode.
|
|
450
1227
|
*
|
|
451
|
-
* @
|
|
452
|
-
* @
|
|
1228
|
+
* @param rootExpression - reader 扫描 `document` 或异步载入的 `contentHost`。Reader scan root: `document` or the asynchronously loaded `contentHost`.
|
|
1229
|
+
* @returns 可直接嵌入 owner script 的确定性 JavaScript 行。Deterministic JavaScript lines embeddable in the owner script.
|
|
453
1230
|
*/
|
|
454
1231
|
function renderProjectSourceFetchClientLines(rootExpression) {
|
|
455
1232
|
return [
|
|
456
|
-
"
|
|
457
|
-
"
|
|
458
|
-
"
|
|
459
|
-
"
|
|
1233
|
+
" const sourceControllers = new WeakMap();",
|
|
1234
|
+
" const sourceTerminalStates = new Set(['ready', 'empty', 'denied', 'not-found', 'integrity-error', 'network-error', 'aborted']);",
|
|
1235
|
+
" function sourceUiMessage(messageId, fallback, values = {}) {",
|
|
1236
|
+
" return typeof uiMessage === 'function' && typeof config !== 'undefined' && config.ui ? uiMessage(messageId, values, fallback) : fallback;",
|
|
1237
|
+
" }",
|
|
1238
|
+
" function setSourceState(details, state, messageId = '', fallback = '', values = {}) {",
|
|
1239
|
+
" const loadButton = details.querySelector('[data-hia-source-fetch-button]');",
|
|
1240
|
+
" const resetButton = details.querySelector('[data-hia-source-reset]');",
|
|
460
1241
|
" const status = details.querySelector('[data-hia-source-fetch-status]');",
|
|
461
|
-
" details.dataset.
|
|
462
|
-
" details.
|
|
1242
|
+
" details.dataset.hiaSourceState = state;",
|
|
1243
|
+
" details.toggleAttribute('aria-busy', state === 'loading');",
|
|
463
1244
|
" if (status) {",
|
|
464
|
-
" status.hidden =
|
|
465
|
-
" status.
|
|
1245
|
+
" status.hidden = state === 'idle';",
|
|
1246
|
+
" if (messageId) status.dataset.hiaUiMessage = messageId; else delete status.dataset.hiaUiMessage;",
|
|
1247
|
+
" if (Object.keys(values).length > 0) status.dataset.hiaUiValues = JSON.stringify(values); else delete status.dataset.hiaUiValues;",
|
|
1248
|
+
" status.textContent = messageId ? sourceUiMessage(messageId, fallback, values) : '';",
|
|
1249
|
+
" }",
|
|
1250
|
+
" if (loadButton) loadButton.hidden = state !== 'idle';",
|
|
1251
|
+
" if (resetButton) {",
|
|
1252
|
+
" resetButton.hidden = state === 'idle';",
|
|
1253
|
+
" const resetMessageId = state === 'loading' ? 'portal.source.cancel' : 'portal.source.reset';",
|
|
1254
|
+
" resetButton.dataset.hiaUiMessage = resetMessageId;",
|
|
1255
|
+
" resetButton.textContent = sourceUiMessage(resetMessageId, state === 'loading' ? 'Cancel' : 'Reset');",
|
|
466
1256
|
" }",
|
|
1257
|
+
" }",
|
|
1258
|
+
" function sourceFailureState(response) {",
|
|
1259
|
+
" if (response.status === 401 || response.status === 403) return 'denied';",
|
|
1260
|
+
" if (response.status === 404) return 'not-found';",
|
|
1261
|
+
" return 'network-error';",
|
|
1262
|
+
" }",
|
|
1263
|
+
" function digestBase64(buffer) {",
|
|
1264
|
+
" return btoa(String.fromCharCode(...new Uint8Array(buffer)));",
|
|
1265
|
+
" }",
|
|
1266
|
+
" async function loadSourceFetch(details) {",
|
|
1267
|
+
" if ((details.dataset.hiaSourceState || 'idle') !== 'idle') return;",
|
|
1268
|
+
" const code = details.querySelector('code');",
|
|
1269
|
+
" const controller = new AbortController();",
|
|
1270
|
+
" const timeoutMs = Math.max(100, Number(details.dataset.hiaSourceTimeout || 10000));",
|
|
1271
|
+
" const timeout = setTimeout(() => controller.abort(), timeoutMs);",
|
|
1272
|
+
" sourceControllers.set(details, controller);",
|
|
1273
|
+
" setSourceState(details, 'loading', 'portal.source.status.loading', 'Loading source...');",
|
|
467
1274
|
" try {",
|
|
468
|
-
"
|
|
469
|
-
"
|
|
470
|
-
"
|
|
471
|
-
"
|
|
1275
|
+
" /* <lang><zh-CN>只允许文档站同源且无 userinfo 的 content-addressed endpoint。</zh-CN><en>Allow only a same-origin content-addressed endpoint without userinfo.</en></lang> */",
|
|
1276
|
+
" const target = new URL(details.dataset.hiaSourceFetch || '', document.baseURI);",
|
|
1277
|
+
" if (target.origin !== location.origin || target.username || target.password) {",
|
|
1278
|
+
" setSourceState(details, 'denied', 'portal.source.status.denied', 'Source request denied.');",
|
|
1279
|
+
" return;",
|
|
1280
|
+
" }",
|
|
1281
|
+
" /* <lang><zh-CN>请求固定无凭据、同源且拒绝 redirect;signal 同时承担取消与超时。</zh-CN><en>The request is credential-free, same-origin, and redirect-denying; the signal covers cancellation and timeout.</en></lang> */",
|
|
1282
|
+
" const response = await fetch(target, { cache: 'default', credentials: 'omit', mode: 'same-origin', redirect: 'error', signal: controller.signal });",
|
|
1283
|
+
" if (!response.ok) {",
|
|
1284
|
+
" const state = sourceFailureState(response);",
|
|
1285
|
+
" const detail = `${response.status} ${response.statusText}`;",
|
|
1286
|
+
" setSourceState(details, state, 'portal.source.status.failed', `Source load failed: ${detail}`, { detail });",
|
|
1287
|
+
" return;",
|
|
1288
|
+
" }",
|
|
1289
|
+
" /* <lang><zh-CN>先验证字节数与 SHA-384,再把公开 asset 解码为不可执行纯文本。</zh-CN><en>Verify byte length and SHA-384 before decoding the public asset as non-executable plain text.</en></lang> */",
|
|
1290
|
+
" const bytes = await response.arrayBuffer();",
|
|
1291
|
+
" const maxBytes = Math.max(1, Number(details.dataset.hiaSourceMaxBytes || 1048576));",
|
|
1292
|
+
" const expectedBytes = Number(details.dataset.hiaSourceByteLength || 0);",
|
|
1293
|
+
" if (bytes.byteLength > maxBytes || (expectedBytes >= 0 && bytes.byteLength !== expectedBytes)) {",
|
|
1294
|
+
" setSourceState(details, 'integrity-error', 'portal.source.status.size', 'Source size verification failed.');",
|
|
1295
|
+
" return;",
|
|
1296
|
+
" }",
|
|
1297
|
+
" const digest = await crypto.subtle.digest('SHA-384', bytes);",
|
|
1298
|
+
" if (`sha384-${digestBase64(digest)}` !== details.dataset.hiaSourceIntegrity) {",
|
|
1299
|
+
" setSourceState(details, 'integrity-error', 'portal.source.status.integrity', 'Source integrity verification failed.');",
|
|
1300
|
+
" return;",
|
|
1301
|
+
" }",
|
|
1302
|
+
" /* <lang><zh-CN>非法 UTF-8 表示 asset 违反 text contract,归入 integrity-error。</zh-CN><en>Invalid UTF-8 violates the text-asset contract and maps to integrity-error.</en></lang> */",
|
|
1303
|
+
" let text;",
|
|
1304
|
+
" try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); }",
|
|
1305
|
+
" catch { setSourceState(details, 'integrity-error', 'portal.source.status.decode', 'Source text decoding failed.'); return; }",
|
|
1306
|
+
" if (text.length === 0) {",
|
|
1307
|
+
" if (code) code.textContent = '';",
|
|
1308
|
+
" setSourceState(details, 'empty', 'portal.source.status.empty', 'Source asset is empty.');",
|
|
1309
|
+
" return;",
|
|
1310
|
+
" }",
|
|
1311
|
+
" /* <lang><zh-CN>只投影配置允许的行数,绝不执行或加入搜索索引。</zh-CN><en>Project only the configured line limit, never executing or search-indexing the body.</en></lang> */",
|
|
1312
|
+
" const lines = text.split(/\\r?\\n/u);",
|
|
472
1313
|
" const maxLines = Math.max(1, Number(details.dataset.hiaSourceMaxLines || 400));",
|
|
473
|
-
"
|
|
474
|
-
"
|
|
475
|
-
" if (code) code.textContent = lines.slice(start - 1, end).join('\\n');",
|
|
476
|
-
" details.dataset.loaded = 'true';",
|
|
477
|
-
" if (button) button.hidden = true;",
|
|
478
|
-
" if (status) status.hidden = true;",
|
|
1314
|
+
" if (code) code.textContent = lines.slice(0, maxLines).join('\\n');",
|
|
1315
|
+
" setSourceState(details, 'ready', 'portal.source.status.ready', 'Source ready.');",
|
|
479
1316
|
" } catch (error) {",
|
|
480
|
-
"
|
|
481
|
-
"
|
|
482
|
-
"
|
|
483
|
-
" button.textContent = 'Retry source / 重试加载源码';",
|
|
484
|
-
" }",
|
|
1317
|
+
" const aborted = error?.name === 'AbortError';",
|
|
1318
|
+
" const detail = String(error?.message || error);",
|
|
1319
|
+
" setSourceState(details, aborted ? 'aborted' : 'network-error', aborted ? 'portal.source.status.aborted' : 'portal.source.status.failed', aborted ? 'Source load aborted.' : `Source load failed: ${detail}`, aborted ? {} : { detail });",
|
|
485
1320
|
" } finally {",
|
|
486
|
-
"
|
|
487
|
-
"
|
|
1321
|
+
" clearTimeout(timeout);",
|
|
1322
|
+
" sourceControllers.delete(details);",
|
|
488
1323
|
" }",
|
|
489
1324
|
" }",
|
|
1325
|
+
" /* <lang><zh-CN>终态必须显式 reset 回 idle;loading 状态的同一操作只负责取消。</zh-CN><en>Terminal states require an explicit reset to idle; the same action only cancels while loading.</en></lang> */",
|
|
1326
|
+
" function resetSourceFetch(details) {",
|
|
1327
|
+
" const state = details.dataset.hiaSourceState || 'idle';",
|
|
1328
|
+
" if (state === 'loading') { sourceControllers.get(details)?.abort(); return; }",
|
|
1329
|
+
" if (!sourceTerminalStates.has(state)) return;",
|
|
1330
|
+
" const code = details.querySelector('code');",
|
|
1331
|
+
" if (code) code.textContent = '';",
|
|
1332
|
+
" setSourceState(details, 'idle');",
|
|
1333
|
+
" }",
|
|
490
1334
|
` function bindSourceFetch(root = ${rootExpression}) {`,
|
|
491
1335
|
" for (const details of root?.querySelectorAll('details[data-hia-source-fetch]') || []) {",
|
|
492
1336
|
" const button = details.querySelector('[data-hia-source-fetch-button]');",
|
|
1337
|
+
" const resetButton = details.querySelector('[data-hia-source-reset]');",
|
|
493
1338
|
" if (button) button.addEventListener('click', () => loadSourceFetch(details));",
|
|
1339
|
+
" if (resetButton) resetButton.addEventListener('click', () => resetSourceFetch(details));",
|
|
1340
|
+
" setSourceState(details, details.dataset.hiaSourceState || 'idle');",
|
|
494
1341
|
" if (details.dataset.hiaSourceFetchTrigger !== 'manual') {",
|
|
495
1342
|
" details.addEventListener('toggle', () => {",
|
|
496
1343
|
" if (details.open) void loadSourceFetch(details);",
|
|
@@ -501,29 +1348,63 @@ function renderProjectSourceFetchClientLines(rootExpression) {
|
|
|
501
1348
|
" }"
|
|
502
1349
|
];
|
|
503
1350
|
}
|
|
504
|
-
function renderProjectSplitSiteScript(
|
|
1351
|
+
function renderProjectSplitSiteScript(portalContext, loadingStrategy) {
|
|
1352
|
+
// <lang><zh-CN>只有 adopted surface 嵌入 public plain-text bundle;metadata-only report 仍不含译文。</zh-CN><en>Only adopted surfaces embed the public plain-text bundle; the metadata-only report still contains no translations.</en></lang>
|
|
1353
|
+
const uiConfig = portalContext.uiLocaleAdoption
|
|
1354
|
+
? {
|
|
1355
|
+
bundles: portalContext.uiLocaleAdoption.bundles,
|
|
1356
|
+
initialLocale: portalContext.uiLocale,
|
|
1357
|
+
supportedLocales: DOCUMENTATION_PORTAL_UI_CATALOG_LOCALES
|
|
1358
|
+
}
|
|
1359
|
+
: null;
|
|
1360
|
+
const fileProtocolMessage = resolveProjectUiPlainText(portalContext, "portal.navigation.requiresserver", {}, portalContext.labels.requiresServer);
|
|
505
1361
|
return [
|
|
506
1362
|
"<script>",
|
|
507
1363
|
"(() => {",
|
|
508
|
-
|
|
1364
|
+
` const config = { navigation: 'navigation/root.json', search: 'search/index.json', relations: 'relations/project.json', loadingStrategy: ${JSON.stringify(loadingStrategy)}, eagerContent: 'content/eager.json', ui: ${JSON.stringify(uiConfig)} };`,
|
|
509
1365
|
" const treeHost = document.querySelector('[data-hia-project-tree]');",
|
|
510
1366
|
" const contentHost = document.querySelector('[data-hia-project-content]');",
|
|
511
1367
|
" const search = document.querySelector('[data-hia-project-search]');",
|
|
512
|
-
" const
|
|
1368
|
+
" const contentLocale = document.querySelector('[data-hia-locale-control]');",
|
|
1369
|
+
" const uiLocale = document.querySelector('[data-hia-ui-locale-control]');",
|
|
513
1370
|
" const viewButtons = Array.from(document.querySelectorAll('[data-hia-project-view]'));",
|
|
514
1371
|
" let rootNodes = [];",
|
|
515
1372
|
" let searchEntries = null;",
|
|
1373
|
+
" let eagerFragments = null;",
|
|
516
1374
|
" let activeView = 'all';",
|
|
1375
|
+
" function uiMessage(messageId, values = {}, fallback = messageId) {",
|
|
1376
|
+
" const selected = String(uiLocale?.value || config.ui?.initialLocale || document.documentElement.lang || 'en');",
|
|
1377
|
+
" const template = config.ui?.bundles?.[selected]?.[messageId] || fallback;",
|
|
1378
|
+
" return template.replace(/\\{([A-Za-z][A-Za-z0-9_]*)\\}/gu, (_match, name) => String(values[name] ?? `{${name}}`));",
|
|
1379
|
+
" }",
|
|
1380
|
+
" function readUiValues(node) {",
|
|
1381
|
+
" try { return JSON.parse(node.getAttribute('data-hia-ui-values') || '{}'); } catch { return {}; }",
|
|
1382
|
+
" }",
|
|
1383
|
+
" function applyUiLocale(root = document) {",
|
|
1384
|
+
" if (!config.ui) return;",
|
|
1385
|
+
" const selected = String(uiLocale?.value || config.ui.initialLocale);",
|
|
1386
|
+
" if (!config.ui.supportedLocales.includes(selected)) return;",
|
|
1387
|
+
" document.documentElement.lang = selected;",
|
|
1388
|
+
" for (const node of root.querySelectorAll('[data-hia-ui-message]')) node.textContent = uiMessage(node.getAttribute('data-hia-ui-message'), readUiValues(node));",
|
|
1389
|
+
" for (const node of root.querySelectorAll('[data-hia-ui-placeholder]')) node.setAttribute('placeholder', uiMessage(node.getAttribute('data-hia-ui-placeholder')));",
|
|
1390
|
+
" for (const node of root.querySelectorAll('[data-hia-ui-aria]')) node.setAttribute('aria-label', uiMessage(node.getAttribute('data-hia-ui-aria')));",
|
|
1391
|
+
" try { localStorage.setItem('hia-doc-portal-ui-locale', selected); } catch {}",
|
|
1392
|
+
" document.dispatchEvent(new CustomEvent('hia:ui-locale-change', { detail: { uiLocale: selected } }));",
|
|
1393
|
+
" }",
|
|
517
1394
|
" async function readJson(target) {",
|
|
518
1395
|
" const response = await fetch(target, { credentials: 'omit' });",
|
|
519
1396
|
" if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);",
|
|
520
1397
|
" return response.json();",
|
|
521
1398
|
" }",
|
|
522
1399
|
" function showLoadError(error) {",
|
|
523
|
-
` const
|
|
1400
|
+
` const detail = location.protocol === 'file:' ? ${JSON.stringify(fileProtocolMessage)} : String(error?.message || error);`,
|
|
1401
|
+
" const hint = location.protocol === 'file:' ? detail : uiMessage('portal.navigation.loaderror', { detail }, detail);",
|
|
524
1402
|
" if (contentHost) contentHost.innerHTML = '';",
|
|
525
1403
|
" const message = document.createElement('p');",
|
|
526
1404
|
" message.className = 'hia-project-load-error';",
|
|
1405
|
+
" message.setAttribute('role', 'status');",
|
|
1406
|
+
" message.dataset.hiaUiMessage = location.protocol === 'file:' ? 'portal.navigation.requiresserver' : 'portal.navigation.loaderror';",
|
|
1407
|
+
" if (location.protocol !== 'file:') message.dataset.hiaUiValues = JSON.stringify({ detail });",
|
|
527
1408
|
" message.textContent = hint;",
|
|
528
1409
|
" (contentHost || treeHost)?.append(message);",
|
|
529
1410
|
" }",
|
|
@@ -539,8 +1420,12 @@ function renderProjectSplitSiteScript(fileProtocolMessage, openLabel) {
|
|
|
539
1420
|
" function createTreeNode(node) {",
|
|
540
1421
|
" const item = document.createElement('li');",
|
|
541
1422
|
" item.dataset.hiaProjectNav = node.views?.[0] || 'other';",
|
|
542
|
-
"
|
|
1423
|
+
" item.dataset.hiaProjectNodeId = node.id || '';",
|
|
1424
|
+
" if (node.entryId) item.dataset.hiaProjectEntryId = node.entryId;",
|
|
1425
|
+
" const inlineChildren = Array.isArray(node.children) ? node.children : [];",
|
|
1426
|
+
" if (node.childrenPath || inlineChildren.length > 0) {",
|
|
543
1427
|
" const details = document.createElement('details');",
|
|
1428
|
+
" details.dataset.hiaProjectDisclosure = node.id || '';",
|
|
544
1429
|
" const summary = document.createElement('summary');",
|
|
545
1430
|
" const summaryLabel = document.createElement('span');",
|
|
546
1431
|
" summaryLabel.textContent = `${node.label} (${node.entryCount})`;",
|
|
@@ -549,36 +1434,44 @@ function renderProjectSplitSiteScript(fileProtocolMessage, openLabel) {
|
|
|
549
1434
|
" const openButton = document.createElement('button');",
|
|
550
1435
|
" openButton.type = 'button';",
|
|
551
1436
|
" openButton.className = 'hia-project-entry-link hia-project-tree-open';",
|
|
552
|
-
|
|
1437
|
+
" openButton.dataset.hiaUiMessage = 'portal.navigation.open';",
|
|
1438
|
+
` openButton.textContent = uiMessage('portal.navigation.open', {}, ${JSON.stringify(portalContext.labels.open)});`,
|
|
553
1439
|
" openButton.addEventListener('click', (event) => {",
|
|
554
1440
|
" event.preventDefault();",
|
|
555
1441
|
" event.stopPropagation();",
|
|
556
|
-
" loadEntry(node
|
|
1442
|
+
" loadEntry(node, true);",
|
|
557
1443
|
" });",
|
|
558
1444
|
" summary.append(openButton);",
|
|
559
1445
|
" }",
|
|
560
1446
|
" details.append(summary);",
|
|
561
|
-
"
|
|
562
|
-
" if (!details.open || details.dataset.loaded === 'true') return;",
|
|
1447
|
+
" if (inlineChildren.length > 0) {",
|
|
563
1448
|
" details.dataset.loaded = 'true';",
|
|
564
|
-
"
|
|
565
|
-
"
|
|
566
|
-
"
|
|
567
|
-
"
|
|
568
|
-
"
|
|
569
|
-
" const
|
|
570
|
-
" loading.
|
|
571
|
-
"
|
|
572
|
-
" loading.
|
|
573
|
-
|
|
574
|
-
"
|
|
1449
|
+
" details.append(createTreeList(inlineChildren));",
|
|
1450
|
+
" } else {",
|
|
1451
|
+
" details.addEventListener('toggle', async () => {",
|
|
1452
|
+
" if (!details.open || details.dataset.loaded === 'true') return;",
|
|
1453
|
+
" details.dataset.loaded = 'true';",
|
|
1454
|
+
" const loading = document.createElement('p');",
|
|
1455
|
+
" loading.className = 'hia-project-loading';",
|
|
1456
|
+
" loading.setAttribute('role', 'status');",
|
|
1457
|
+
" loading.dataset.hiaUiMessage = 'portal.navigation.loading';",
|
|
1458
|
+
` loading.textContent = uiMessage('portal.navigation.loading', {}, ${JSON.stringify(portalContext.labels.loading)});`,
|
|
1459
|
+
" details.append(loading);",
|
|
1460
|
+
" try {",
|
|
1461
|
+
" const shard = await readJson(node.childrenPath);",
|
|
1462
|
+
" loading.replaceWith(createTreeList(Array.isArray(shard.children) ? shard.children : []));",
|
|
1463
|
+
" } catch (error) {",
|
|
1464
|
+
" loading.textContent = String(error?.message || error);",
|
|
1465
|
+
" }",
|
|
1466
|
+
" });",
|
|
1467
|
+
" }",
|
|
575
1468
|
" item.append(details);",
|
|
576
1469
|
" } else if (node.entryId && node.contentPath) {",
|
|
577
1470
|
" const button = document.createElement('button');",
|
|
578
1471
|
" button.type = 'button';",
|
|
579
1472
|
" button.className = 'hia-project-entry-link';",
|
|
580
1473
|
" button.textContent = node.label;",
|
|
581
|
-
" button.addEventListener('click', () => loadEntry(node
|
|
1474
|
+
" button.addEventListener('click', () => loadEntry(node, true));",
|
|
582
1475
|
" item.append(button);",
|
|
583
1476
|
" } else {",
|
|
584
1477
|
" const label = document.createElement('span');",
|
|
@@ -590,26 +1483,62 @@ function renderProjectSplitSiteScript(fileProtocolMessage, openLabel) {
|
|
|
590
1483
|
" function renderRoot() {",
|
|
591
1484
|
" if (!treeHost) return;",
|
|
592
1485
|
" treeHost.innerHTML = '';",
|
|
593
|
-
" treeHost.append(createTreeList(rootNodes));",
|
|
1486
|
+
" if (rootNodes.length > 0) { treeHost.append(createTreeList(rootNodes)); return; }",
|
|
1487
|
+
" /* <lang><zh-CN>空项目仍生成带稳定 message identity 的可翻译状态。</zh-CN><en>An empty project still renders a translatable state with a stable message identity.</en></lang> */",
|
|
1488
|
+
" const empty = document.createElement('p');",
|
|
1489
|
+
" empty.className = 'hia-project-empty';",
|
|
1490
|
+
" empty.dataset.hiaUiMessage = 'portal.common.noentries';",
|
|
1491
|
+
" empty.textContent = uiMessage('portal.common.noentries', {}, 'No project documentation entries.');",
|
|
1492
|
+
" treeHost.append(empty);",
|
|
594
1493
|
" }",
|
|
595
|
-
" function
|
|
596
|
-
" const selected = String(
|
|
597
|
-
" document.documentElement.lang = selected;",
|
|
1494
|
+
" function applyContentLocale() {",
|
|
1495
|
+
" const selected = String(contentLocale?.value || 'und');",
|
|
598
1496
|
" for (const block of document.querySelectorAll('[data-hia-locale]')) {",
|
|
599
1497
|
" block.hidden = block.getAttribute('data-hia-locale') !== selected;",
|
|
600
1498
|
" }",
|
|
601
1499
|
" }",
|
|
602
1500
|
...renderProjectSourceFetchClientLines("contentHost"),
|
|
603
|
-
" async function
|
|
1501
|
+
" async function ensureEagerFragments() {",
|
|
1502
|
+
" if (config.loadingStrategy !== 'eager') return null;",
|
|
1503
|
+
" if (eagerFragments) return eagerFragments;",
|
|
1504
|
+
" const index = await readJson(config.eagerContent);",
|
|
1505
|
+
" eagerFragments = new Map((Array.isArray(index.fragments) ? index.fragments : []).map((fragment) => [fragment.path, fragment.contents]));",
|
|
1506
|
+
" return eagerFragments;",
|
|
1507
|
+
" }",
|
|
1508
|
+
" async function readFragment(path) {",
|
|
1509
|
+
" const eager = await ensureEagerFragments();",
|
|
1510
|
+
" if (eager?.has(path)) return eager.get(path);",
|
|
1511
|
+
" const response = await fetch(path, { credentials: 'omit' });",
|
|
1512
|
+
" if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);",
|
|
1513
|
+
" return response.text();",
|
|
1514
|
+
" }",
|
|
1515
|
+
" function markActiveEntry(entryId) {",
|
|
1516
|
+
" for (const item of document.querySelectorAll('[data-hia-project-node-id]')) {",
|
|
1517
|
+
" delete item.dataset.hiaActiveEntry;",
|
|
1518
|
+
" for (const details of item.querySelectorAll(':scope > details')) delete details.dataset.hiaActiveAncestor;",
|
|
1519
|
+
" }",
|
|
1520
|
+
" const leaf = Array.from(document.querySelectorAll('[data-hia-project-entry-id]')).find((item) => item.dataset.hiaProjectEntryId === entryId);",
|
|
1521
|
+
" if (!leaf) return;",
|
|
1522
|
+
" leaf.dataset.hiaActiveEntry = 'true';",
|
|
1523
|
+
" for (const details of leaf.parentElement?.closest('details') ? [leaf.parentElement.closest('details')] : []) {",
|
|
1524
|
+
" let current = details;",
|
|
1525
|
+
" while (current) { current.open = true; current.dataset.hiaActiveAncestor = 'true'; current = current.parentElement?.closest('details'); }",
|
|
1526
|
+
" }",
|
|
1527
|
+
" }",
|
|
1528
|
+
" async function loadEntry(entry, updateHash) {",
|
|
604
1529
|
" if (!contentHost) return;",
|
|
605
|
-
|
|
1530
|
+
` contentHost.innerHTML = \`<p class="hia-project-loading" role="status" data-hia-ui-message="portal.navigation.loading">\${uiMessage('portal.navigation.loading', {}, ${JSON.stringify(portalContext.labels.loading)})}</p>\`;`,
|
|
606
1531
|
" try {",
|
|
607
|
-
" const
|
|
608
|
-
"
|
|
609
|
-
"
|
|
610
|
-
"
|
|
1532
|
+
" const contentPath = entry.presentationPath || entry.contentPath;",
|
|
1533
|
+
" contentHost.innerHTML = await readFragment(contentPath);",
|
|
1534
|
+
" applyContentLocale();",
|
|
1535
|
+
" applyUiLocale(contentHost);",
|
|
611
1536
|
" bindSourceFetch();",
|
|
612
|
-
"
|
|
1537
|
+
" const anchor = entry.memberAnchor || entry.entryId || entry.id;",
|
|
1538
|
+
" const target = Array.from(contentHost.querySelectorAll('[id]')).find((item) => item.id === anchor);",
|
|
1539
|
+
" target?.scrollIntoView({ block: 'start' });",
|
|
1540
|
+
" markActiveEntry(entry.entryId || entry.id);",
|
|
1541
|
+
" if (updateHash) history.replaceState(null, '', `#entry=${encodeURIComponent(entry.entryId || entry.id)}`);",
|
|
613
1542
|
" } catch (error) {",
|
|
614
1543
|
" showLoadError(error);",
|
|
615
1544
|
" }",
|
|
@@ -628,8 +1557,16 @@ function renderProjectSplitSiteScript(fileProtocolMessage, openLabel) {
|
|
|
628
1557
|
" const matches = entries.filter((entry) => (activeView === 'all' || entry.view === activeView) && String(entry.searchText || '').includes(query)).slice(0, 200);",
|
|
629
1558
|
" if (!treeHost) return;",
|
|
630
1559
|
" treeHost.innerHTML = '';",
|
|
631
|
-
" const nodes = matches.map((entry) => ({ id: entry.id, label: `${entry.name} · ${entry.kind}`, entryId: entry.id, contentPath: entry.contentPath, views: [entry.view], entryCount: 1 }));",
|
|
632
|
-
" treeHost.append(createTreeList(nodes));",
|
|
1560
|
+
" const nodes = matches.map((entry) => ({ id: entry.id, label: `${entry.name} · ${entry.kind}`, entryId: entry.id, contentPath: entry.contentPath, presentationPath: entry.presentationPath, memberAnchor: entry.memberAnchor, views: [entry.view], entryCount: 1 }));",
|
|
1561
|
+
" if (nodes.length > 0) { treeHost.append(createTreeList(nodes)); return; }",
|
|
1562
|
+
" /* <lang><zh-CN>筛选空结果使用 polite status,同时保留独立的 message identity。</zh-CN><en>An empty filter result uses a polite status while retaining its own message identity.</en></lang> */",
|
|
1563
|
+
" const empty = document.createElement('p');",
|
|
1564
|
+
" empty.className = 'hia-project-empty';",
|
|
1565
|
+
" empty.setAttribute('role', 'status');",
|
|
1566
|
+
" empty.setAttribute('aria-live', 'polite');",
|
|
1567
|
+
" empty.dataset.hiaUiMessage = 'portal.common.nomatches';",
|
|
1568
|
+
" empty.textContent = uiMessage('portal.common.nomatches', {}, 'No entries match the current filters.');",
|
|
1569
|
+
" treeHost.append(empty);",
|
|
633
1570
|
" } catch (error) { showLoadError(error); }",
|
|
634
1571
|
" }",
|
|
635
1572
|
" for (const button of viewButtons) {",
|
|
@@ -640,7 +1577,8 @@ function renderProjectSplitSiteScript(fileProtocolMessage, openLabel) {
|
|
|
640
1577
|
" });",
|
|
641
1578
|
" }",
|
|
642
1579
|
" search?.addEventListener('input', runSearch);",
|
|
643
|
-
"
|
|
1580
|
+
" contentLocale?.addEventListener('change', applyContentLocale);",
|
|
1581
|
+
" uiLocale?.addEventListener('change', () => applyUiLocale());",
|
|
644
1582
|
" document.querySelector('[data-hia-project-relations]')?.addEventListener('click', async () => {",
|
|
645
1583
|
" try {",
|
|
646
1584
|
" const graph = await readJson(config.relations);",
|
|
@@ -649,9 +1587,12 @@ function renderProjectSplitSiteScript(fileProtocolMessage, openLabel) {
|
|
|
649
1587
|
" const article = document.createElement('article');",
|
|
650
1588
|
" article.className = 'hia-symbol';",
|
|
651
1589
|
" const heading = document.createElement('h2');",
|
|
652
|
-
" heading.
|
|
1590
|
+
" heading.dataset.hiaUiMessage = 'portal.navigation.relations';",
|
|
1591
|
+
` heading.textContent = uiMessage('portal.navigation.relations', {}, ${JSON.stringify(portalContext.labels.relations)});`,
|
|
653
1592
|
" const summary = document.createElement('p');",
|
|
654
|
-
" summary.
|
|
1593
|
+
" summary.dataset.hiaUiMessage = 'portal.navigation.relationsummary';",
|
|
1594
|
+
" summary.dataset.hiaUiValues = JSON.stringify({ nodes: graph.nodeCount || 0, relations: graph.relationCount || 0 });",
|
|
1595
|
+
" summary.textContent = uiMessage('portal.navigation.relationsummary', { nodes: graph.nodeCount || 0, relations: graph.relationCount || 0 }, `${graph.nodeCount || 0} nodes, ${graph.relationCount || 0} relations`);",
|
|
655
1596
|
" article.append(heading, summary);",
|
|
656
1597
|
" contentHost.append(article);",
|
|
657
1598
|
" } catch (error) { showLoadError(error); }",
|
|
@@ -662,15 +1603,23 @@ function renderProjectSplitSiteScript(fileProtocolMessage, openLabel) {
|
|
|
662
1603
|
" const hash = location.hash.startsWith('#entry=') ? decodeURIComponent(location.hash.slice(7)) : '';",
|
|
663
1604
|
" if (hash) ensureSearchIndex().then((entries) => {",
|
|
664
1605
|
" const entry = entries.find((candidate) => candidate.id === hash);",
|
|
665
|
-
" if (entry) loadEntry(entry
|
|
1606
|
+
" if (entry) loadEntry({ ...entry, entryId: entry.id }, false);",
|
|
666
1607
|
" });",
|
|
667
1608
|
" }).catch(showLoadError);",
|
|
1609
|
+
" if (config.ui && uiLocale) {",
|
|
1610
|
+
" try {",
|
|
1611
|
+
" const saved = localStorage.getItem('hia-doc-portal-ui-locale');",
|
|
1612
|
+
" if (saved && config.ui.supportedLocales.includes(saved)) uiLocale.value = saved;",
|
|
1613
|
+
" } catch {}",
|
|
1614
|
+
" }",
|
|
1615
|
+
" applyContentLocale();",
|
|
1616
|
+
" applyUiLocale();",
|
|
668
1617
|
" viewButtons.find((button) => button.dataset.hiaProjectView === 'all')?.setAttribute('aria-pressed', 'true');",
|
|
669
1618
|
"})();",
|
|
670
1619
|
"</script>"
|
|
671
1620
|
].join("");
|
|
672
1621
|
}
|
|
673
|
-
function renderProjectIndexHtml(pageTitle, projectInput, options) {
|
|
1622
|
+
function renderProjectIndexHtml(pageTitle, projectInput, options, portalContext) {
|
|
674
1623
|
const projectName = projectInput.project.title ?? projectInput.project.name;
|
|
675
1624
|
const localeModel = resolveProjectLocaleModel(projectInput, options.locale);
|
|
676
1625
|
const views = collectProjectViews(projectInput.entries);
|
|
@@ -687,10 +1636,11 @@ function renderProjectIndexHtml(pageTitle, projectInput, options) {
|
|
|
687
1636
|
const docSourceMapSummary = renderProjectDocSourceMaps(projectInput.docSourceMaps ?? []);
|
|
688
1637
|
const relationGraphSummary = renderProjectRelationGraphSummary(projectInput.relationGraph);
|
|
689
1638
|
const relationGraph = renderProjectRelationGraph(projectInput.relationGraph);
|
|
1639
|
+
const generatedDocumentationBindingProjection = renderProjectGeneratedDocumentationBindingProjection(projectInput.generatedDocumentationBindingProjection);
|
|
690
1640
|
const diagnostics = renderProjectDiagnostics(projectInput.diagnostics ?? []);
|
|
691
1641
|
return [
|
|
692
1642
|
"<!doctype html>",
|
|
693
|
-
`<html lang="${escapeHtml(localeModel.selectedLocale)}">`,
|
|
1643
|
+
`<html lang="${escapeHtml(localeModel.selectedLocale)}" ${renderDefaultThemeRootAttributes(portalContext.theme)}>`,
|
|
694
1644
|
"<head>",
|
|
695
1645
|
"<meta charset=\"utf-8\">",
|
|
696
1646
|
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">",
|
|
@@ -703,6 +1653,7 @@ function renderProjectIndexHtml(pageTitle, projectInput, options) {
|
|
|
703
1653
|
"<aside class=\"hia-sidebar\">",
|
|
704
1654
|
`<h1>${escapeHtml(projectName)}</h1>`,
|
|
705
1655
|
renderLocaleControl(localeModel.locales, localeModel.selectedLocale),
|
|
1656
|
+
renderProjectThemeControl(portalContext.theme),
|
|
706
1657
|
renderProjectViewControl(views, entryCounts),
|
|
707
1658
|
renderProjectSearchControl(),
|
|
708
1659
|
renderProjectHierarchy(navigationTree),
|
|
@@ -711,6 +1662,7 @@ function renderProjectIndexHtml(pageTitle, projectInput, options) {
|
|
|
711
1662
|
profileSummary,
|
|
712
1663
|
docSourceMapSummary,
|
|
713
1664
|
relationGraphSummary,
|
|
1665
|
+
generatedDocumentationBindingProjection,
|
|
714
1666
|
diagnostics,
|
|
715
1667
|
"</aside>",
|
|
716
1668
|
"<main class=\"hia-main hia-project-main\">",
|
|
@@ -725,9 +1677,9 @@ function renderProjectIndexHtml(pageTitle, projectInput, options) {
|
|
|
725
1677
|
"</html>"
|
|
726
1678
|
].join("");
|
|
727
1679
|
}
|
|
728
|
-
function renderProjectViewControl(views, entryCounts) {
|
|
1680
|
+
function renderProjectViewControl(views, entryCounts, portalContext) {
|
|
729
1681
|
const buttons = views
|
|
730
|
-
.map((view) => `<button type="button" class="hia-project-view-button" data-hia-project-view="${escapeHtml(view)}">${
|
|
1682
|
+
.map((view) => `<button type="button" class="hia-project-view-button" data-hia-project-view="${escapeHtml(view)}">${renderOptionalProjectUiMessage(portalContext, `portal.view.${view}`, formatProjectViewLabel(view))}<span>${escapeHtml(String(entryCounts[view] ?? 0))}</span></button>`)
|
|
731
1683
|
.join("");
|
|
732
1684
|
return `<div class="hia-project-views">${buttons}</div>`;
|
|
733
1685
|
}
|
|
@@ -739,6 +1691,32 @@ function renderProjectSearchControl() {
|
|
|
739
1691
|
"</label>"
|
|
740
1692
|
].join("");
|
|
741
1693
|
}
|
|
1694
|
+
/**
|
|
1695
|
+
* @lang zh-CN 渲染可见的 Portal-owned skin/scheme 选择器;无脚本默认由 `<html>` attributes 决定。
|
|
1696
|
+
* @lang en Renders visible Portal-owned skin/scheme selectors; `<html>` attributes own the no-script default.
|
|
1697
|
+
*/
|
|
1698
|
+
function renderProjectThemeControl(theme, portalContext) {
|
|
1699
|
+
const skins = PORTAL_THEME_SKIN_IDS.map((skinId) => {
|
|
1700
|
+
const messageId = `portal.theme.skin.${skinId.slice("portal.".length)}`;
|
|
1701
|
+
const marked = portalContext?.uiLocaleAdoption
|
|
1702
|
+
? renderProjectUiMarkedText(portalContext, messageId, {})
|
|
1703
|
+
: { attributes: "", text: escapeHtml(getPortalThemeSkinLabel(skinId)) };
|
|
1704
|
+
return `<option value="${escapeHtml(skinId)}"${skinId === theme.skinId ? " selected" : ""}${marked.attributes}>${marked.text}</option>`;
|
|
1705
|
+
}).join("");
|
|
1706
|
+
const schemes = PORTAL_THEME_SCHEMES.map((scheme) => {
|
|
1707
|
+
const messageId = `portal.theme.scheme.${scheme}`;
|
|
1708
|
+
const marked = portalContext?.uiLocaleAdoption
|
|
1709
|
+
? renderProjectUiMarkedText(portalContext, messageId, {})
|
|
1710
|
+
: { attributes: "", text: escapeHtml(getPortalThemeSchemeLabel(scheme)) };
|
|
1711
|
+
return `<option value="${escapeHtml(scheme)}"${scheme === theme.scheme ? " selected" : ""}${marked.attributes}>${marked.text}</option>`;
|
|
1712
|
+
}).join("");
|
|
1713
|
+
return [
|
|
1714
|
+
"<div class=\"hia-theme-switch\" data-hia-theme-control>",
|
|
1715
|
+
`<label>${renderOptionalProjectUiMessage(portalContext, "portal.theme.skinlabel", "Skin / 皮肤")}<select data-hia-skin-control>${skins}</select></label>`,
|
|
1716
|
+
`<label>${renderOptionalProjectUiMessage(portalContext, "portal.theme.schemelabel", "Scheme / 配色")}<select data-hia-scheme-control>${schemes}</select></label>`,
|
|
1717
|
+
"</div>"
|
|
1718
|
+
].join("");
|
|
1719
|
+
}
|
|
742
1720
|
function renderProjectGroupSummary(groups) {
|
|
743
1721
|
if (groups.length === 0) {
|
|
744
1722
|
return "";
|
|
@@ -800,13 +1778,17 @@ function renderProjectNavItem(entry) {
|
|
|
800
1778
|
"</li>"
|
|
801
1779
|
].join("");
|
|
802
1780
|
}
|
|
1781
|
+
/** @lang zh-CN 将项目条目作为完整API参考渲染;本地化正文与单文档复用同一formatter,不将导航摘要当完整正文。 @lang en Renders a project entry as a complete API reference, sharing the document field formatter rather than treating a navigation summary as full prose. */
|
|
803
1782
|
function renderProjectEntry(entry, locales, selectedLocale) {
|
|
804
1783
|
const signature = entry.signature ? `<pre class="hia-signature"><code>${escapeHtml(entry.signature)}</code></pre>` : "";
|
|
805
1784
|
const summary = renderProjectEntrySummary(entry, locales, selectedLocale);
|
|
1785
|
+
// <lang><zh-CN>只排除已作为主描述显示的一个字段,保留同时存在的summary/description及未知扩展字段。</zh-CN><en>Exclude only the one primary field already shown, retaining coexisting summary/description and unknown extensions.</en></lang>
|
|
1786
|
+
const otherFields = renderAdditionalI18nFields(entry, locales, selectedLocale, getPrimaryI18nFieldPath(entry));
|
|
806
1787
|
const input = entry.input ? renderProjectEntryInput(entry.input) : "";
|
|
807
1788
|
const profile = entry.profile ? renderProjectEntryProfile(entry.profile) : "";
|
|
808
1789
|
const hierarchy = entry.hierarchy ? renderProjectEntryHierarchy(entry.hierarchy) : "";
|
|
809
1790
|
const source = entry.source ? renderProjectEntrySource(entry.source) : "";
|
|
1791
|
+
const sourceUsability = entry.sourceUsability ? renderProjectEntrySourceUsability(entry.sourceUsability) : "";
|
|
810
1792
|
const docSourceMap = entry.docSourceMap ? renderProjectEntryDocSourceMap(entry.docSourceMap) : "";
|
|
811
1793
|
const diagnostics = renderProjectDiagnostics(entry.diagnostics ?? []);
|
|
812
1794
|
const searchText = createProjectEntrySearchText(entry);
|
|
@@ -817,15 +1799,256 @@ function renderProjectEntry(entry, locales, selectedLocale) {
|
|
|
817
1799
|
`<span class="hia-kind">${escapeHtml(formatProjectViewLabel(entry.view))}</span>`,
|
|
818
1800
|
signature,
|
|
819
1801
|
summary,
|
|
1802
|
+
otherFields,
|
|
820
1803
|
input,
|
|
821
1804
|
profile,
|
|
822
1805
|
hierarchy,
|
|
823
1806
|
source,
|
|
1807
|
+
sourceUsability,
|
|
824
1808
|
docSourceMap,
|
|
825
1809
|
diagnostics,
|
|
826
1810
|
"</article>"
|
|
827
1811
|
].join("");
|
|
828
1812
|
}
|
|
1813
|
+
/**
|
|
1814
|
+
* 按固定 section order 渲染显式 IA topic;不适用 section 可省略,但 coverage/provenance 明示 unavailable。
|
|
1815
|
+
* Renders an explicit IA topic in fixed section order; inapplicable sections may be omitted while coverage/provenance state unavailability explicitly.
|
|
1816
|
+
*/
|
|
1817
|
+
function renderProjectSemanticTopic(entry, projectInput, locales, selectedLocale, portalContext, includeMemberBodies) {
|
|
1818
|
+
return renderProjectSemanticTopicInternal(entry, projectInput, locales, selectedLocale, portalContext, includeMemberBodies, new Set());
|
|
1819
|
+
}
|
|
1820
|
+
/** 递归 member projection 保持 cycle-safe;cycle 时回退 canonical link。Recursive member projection is cycle-safe and falls back to canonical links on cycles. */
|
|
1821
|
+
function renderProjectSemanticTopicInternal(entry, projectInput, locales, selectedLocale, portalContext, includeMemberBodies, ancestors) {
|
|
1822
|
+
const labels = portalContext.labels;
|
|
1823
|
+
const nextAncestors = new Set(ancestors);
|
|
1824
|
+
nextAncestors.add(entry.id);
|
|
1825
|
+
const members = collectProjectEntryMembers(entry, projectInput.entries);
|
|
1826
|
+
const sections = [
|
|
1827
|
+
// <lang><zh-CN>显式IA保留既有section顺序,在正文分区内加入完整字段,避免建立第二条内容降级路径。</zh-CN><en>Explicit IA retains section order while including full fields inside the prose section, avoiding a second content-loss route.</en></lang>
|
|
1828
|
+
renderProjectTopicSection("summary", "portal.section.summary", labels.summary, renderProjectEntrySummary(entry, locales, selectedLocale) + renderAdditionalI18nFields(entry, locales, selectedLocale, getPrimaryI18nFieldPath(entry)), portalContext),
|
|
1829
|
+
renderProjectTopicSection("declaration", "portal.section.declaration", labels.declaration, entry.signature ? `<pre class="hia-signature"><code>${escapeHtml(entry.signature)}</code></pre>` : "", portalContext),
|
|
1830
|
+
renderProjectTopicSection("metadata", "portal.section.metadata", labels.metadata, renderProjectTopicMetadata(entry, projectInput.project.productVersion, portalContext), portalContext),
|
|
1831
|
+
renderProjectTopicSection("contract", "portal.section.contract", labels.contract, renderProjectTopicContract(entry, portalContext), portalContext),
|
|
1832
|
+
renderProjectTopicSection("coverage", "portal.section.coverage", labels.coverage, renderProjectTopicCoverage(projectInput.documentationContinuity, projectInput.ownerAdoption, portalContext), portalContext),
|
|
1833
|
+
renderProjectTopicSection("provenance", "portal.section.provenance", labels.provenance, renderProjectTopicProvenance(projectInput.documentationContinuity, projectInput.ownerAdoption, portalContext), portalContext),
|
|
1834
|
+
renderProjectTopicSection("members", "portal.section.members", labels.members, renderProjectTopicMembers(members, projectInput, locales, selectedLocale, portalContext, includeMemberBodies, nextAncestors), portalContext),
|
|
1835
|
+
renderProjectTopicSection("relations", "portal.section.relations", labels.relations, renderProjectTopicRelations(entry, projectInput.relationGraph, portalContext), portalContext),
|
|
1836
|
+
renderProjectTopicSection("source", "portal.section.source", labels.source, renderProjectTopicSource(entry, portalContext), portalContext),
|
|
1837
|
+
renderProjectTopicSection("diagnostics", "portal.section.diagnostics", labels.diagnostics, renderProjectTopicDiagnostics(entry.diagnostics ?? []), portalContext)
|
|
1838
|
+
].join("");
|
|
1839
|
+
const searchText = createProjectEntrySearchText(entry);
|
|
1840
|
+
return [
|
|
1841
|
+
`<article class="hia-symbol hia-project-entry hia-project-topic" id="${escapeHtml(entry.id)}" data-hia-project-entry="${escapeHtml(entry.view)}" data-hia-project-search-text="${escapeHtml(searchText)}">`,
|
|
1842
|
+
`<header class="hia-project-topic-header"><h2>${escapeHtml(entry.name)}</h2><span class="hia-kind">${escapeHtml(entry.kind)}</span><span class="hia-kind">${escapeHtml(formatProjectViewLabel(entry.view))}</span></header>`,
|
|
1843
|
+
sections,
|
|
1844
|
+
"</article>"
|
|
1845
|
+
].join("");
|
|
1846
|
+
}
|
|
1847
|
+
/** 空 section 不输出,从而保持“按适用性呈现”。Omits empty sections so topics remain applicability-aware. */
|
|
1848
|
+
function renderProjectTopicSection(section, messageId, label, body, portalContext) {
|
|
1849
|
+
if (!body) {
|
|
1850
|
+
return "";
|
|
1851
|
+
}
|
|
1852
|
+
// <lang><zh-CN>首要阅读区默认展开;其余区保持原生 disclosure,可同时打开且不依赖脚本。</zh-CN><en>Primary reading sections start open; remaining sections use native disclosure, allow concurrent expansion, and require no script.</en></lang>
|
|
1853
|
+
const open = section === "summary" || section === "declaration" || section === "metadata" ? " open" : "";
|
|
1854
|
+
return `<details class="hia-project-topic-section" data-hia-topic-section="${section}"${open}><summary>${renderProjectUiMessage(portalContext, messageId, {}, label)}</summary><div class="hia-project-topic-section-body">${body}</div></details>`;
|
|
1855
|
+
}
|
|
1856
|
+
/** metadata 只含公开 entry/project facts;关系由 relations section 独立承载。Metadata contains public entry/project facts only; relations stay in their own section. */
|
|
1857
|
+
function renderProjectTopicMetadata(entry, productVersion, portalContext) {
|
|
1858
|
+
const items = [
|
|
1859
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.metadata.kind", {}, "Kind")}</dt><dd>${escapeHtml(entry.kind)}</dd>`,
|
|
1860
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.metadata.view", {}, "View")}</dt><dd>${escapeHtml(entry.view)}</dd>`,
|
|
1861
|
+
productVersion ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.productversion", {}, "Product Version")}</dt><dd>${escapeHtml(productVersion)}</dd>` : "",
|
|
1862
|
+
entry.input ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.input", {}, "Input")}</dt><dd>${escapeHtml(entry.input.kind)}</dd>` : "",
|
|
1863
|
+
entry.input?.path ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.inputpath", {}, "Input Path")}</dt><dd>${escapeHtml(entry.input.path)}</dd>` : "",
|
|
1864
|
+
entry.profile ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.profile", {}, "Profile")}</dt><dd>${escapeHtml(entry.profile.profileId)}${entry.profile.profileVersion ? `@${escapeHtml(entry.profile.profileVersion)}` : ""}</dd>` : "",
|
|
1865
|
+
entry.hierarchy?.assembly ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.assembly", {}, "Assembly")}</dt><dd>${escapeHtml(entry.hierarchy.assembly)}</dd>` : "",
|
|
1866
|
+
entry.hierarchy?.namespace ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.namespace", {}, "Namespace")}</dt><dd>${escapeHtml(entry.hierarchy.namespace)}</dd>` : "",
|
|
1867
|
+
entry.hierarchy?.containingType ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.containingtype", {}, "Containing Type")}</dt><dd>${escapeHtml(entry.hierarchy.containingType)}</dd>` : "",
|
|
1868
|
+
entry.hierarchy?.symbolDocumentationId ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.documentationid", {}, "Documentation ID")}</dt><dd>${escapeHtml(entry.hierarchy.symbolDocumentationId)}</dd>` : ""
|
|
1869
|
+
].join("");
|
|
1870
|
+
return `<dl class="hia-project-meta">${items}</dl>`;
|
|
1871
|
+
}
|
|
1872
|
+
/** contract section 与 input locator 分离,避免 path 被误当 contract identity。Separates contract identity from the input locator so paths are not mistaken for contracts. */
|
|
1873
|
+
function renderProjectTopicContract(entry, portalContext) {
|
|
1874
|
+
if (!entry.input?.contract && !entry.input?.contractVersion && !entry.input?.artifactId) {
|
|
1875
|
+
return "";
|
|
1876
|
+
}
|
|
1877
|
+
const items = [
|
|
1878
|
+
entry.input.contract ? `<dt>${renderProjectUiMessage(portalContext, "portal.section.contract", {}, "Contract")}</dt><dd>${escapeHtml(entry.input.contract)}</dd>` : "",
|
|
1879
|
+
entry.input.contractVersion ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.version", {}, "Version")}</dt><dd>${escapeHtml(entry.input.contractVersion)}</dd>` : "",
|
|
1880
|
+
entry.input.artifactId ? `<dt>${renderProjectUiMessage(portalContext, "portal.metadata.artifact", {}, "Artifact")}</dt><dd>${escapeHtml(entry.input.artifactId)}</dd>` : ""
|
|
1881
|
+
].join("");
|
|
1882
|
+
return `<dl class="hia-project-meta">${items}</dl>`;
|
|
1883
|
+
}
|
|
1884
|
+
/** continuity 缺失时不猜测成功,明确输出 unavailable。Never guesses continuity success; absence is rendered as unavailable. */
|
|
1885
|
+
function renderProjectTopicCoverage(continuity, ownerAdoption, portalContext) {
|
|
1886
|
+
if (!continuity && !ownerAdoption) {
|
|
1887
|
+
return `<p class="hia-project-unavailable">${renderProjectUiMessage(portalContext, "portal.common.unavailable", {}, portalContext.labels.unavailable)}</p>`;
|
|
1888
|
+
}
|
|
1889
|
+
return [
|
|
1890
|
+
"<dl class=\"hia-project-meta\">",
|
|
1891
|
+
...(continuity ? [
|
|
1892
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.coverage.continuitystatus", {}, "Continuity Status")}</dt><dd>${escapeHtml(continuity.status)}</dd>`,
|
|
1893
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.coverage.entries", {}, "Entries")}</dt><dd>${escapeHtml(String(continuity.entries.baselineCount))} → ${escapeHtml(String(continuity.entries.currentCount))}</dd>`,
|
|
1894
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.coverage.delta", {}, "Added / Removed / Unchanged")}</dt><dd>${escapeHtml(String(continuity.entries.addedCount))} / ${escapeHtml(String(continuity.entries.removedCount))} / ${escapeHtml(String(continuity.entries.unchangedCount))}</dd>`,
|
|
1895
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.coverage.requiredoutputs", {}, "Required Outputs")}</dt><dd>${renderProjectUiMessage(portalContext, continuity.requiredOutputsPreserved ? "portal.coverage.preserved" : "portal.coverage.notpreserved", {}, continuity.requiredOutputsPreserved ? "preserved" : "not-preserved")}</dd>`
|
|
1896
|
+
] : []),
|
|
1897
|
+
...(ownerAdoption ? [
|
|
1898
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.coverage.ownerreadiness", {}, "Owner Review Readiness")}</dt><dd>${escapeHtml(ownerAdoption.status)}</dd>`,
|
|
1899
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.coverage.ownerinput", {}, "Owner Input / Consent")}</dt><dd>${renderProjectUiMessage(portalContext, ownerAdoption.ownerInput.submitted ? "portal.coverage.submitted" : "portal.coverage.notsubmitted", {}, ownerAdoption.ownerInput.submitted ? "submitted" : "not-submitted")} / ${escapeHtml(ownerAdoption.ownerInput.consent)}</dd>`,
|
|
1900
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.coverage.contractrefs", {}, "Contract References")}</dt><dd>${escapeHtml(String(ownerAdoption.contracts.providedCount))} / ${escapeHtml(String(ownerAdoption.contracts.requiredCount))}</dd>`,
|
|
1901
|
+
...(ownerAdoption.workspaceHandoff ? [
|
|
1902
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.coverage.handoffs", {}, "Repository Owners / Handoff Edges")}</dt><dd>${escapeHtml(String(ownerAdoption.workspaceHandoff.repositoryOwnerCount))} / ${escapeHtml(String(ownerAdoption.workspaceHandoff.handoffEdgeCount))}</dd>`
|
|
1903
|
+
] : [])
|
|
1904
|
+
] : []),
|
|
1905
|
+
"</dl>"
|
|
1906
|
+
].join("");
|
|
1907
|
+
}
|
|
1908
|
+
/** provenance 只显示 exact contract 与三维 semantics,不回读 evidence body。Provenance shows only the exact contract and three semantic dimensions, without reading evidence bodies. */
|
|
1909
|
+
function renderProjectTopicProvenance(continuity, ownerAdoption, portalContext) {
|
|
1910
|
+
if (!continuity && !ownerAdoption) {
|
|
1911
|
+
return `<p class="hia-project-unavailable">${renderProjectUiMessage(portalContext, "portal.common.unavailable", {}, portalContext.labels.unavailable)}</p>`;
|
|
1912
|
+
}
|
|
1913
|
+
return [
|
|
1914
|
+
"<dl class=\"hia-project-meta\">",
|
|
1915
|
+
...(continuity ? [
|
|
1916
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.provenance.continuitycontract", {}, "Continuity Contract")}</dt><dd>${escapeHtml(continuity.contract)}@${escapeHtml(continuity.contractVersion)}</dd>`,
|
|
1917
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.provenance.continuityresolution", {}, "Continuity Resolution")}</dt><dd>${escapeHtml(continuity.semantics.resolution)}</dd>`,
|
|
1918
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.provenance.continuityconfidence", {}, "Continuity Confidence")}</dt><dd>${escapeHtml(continuity.semantics.confidence)}</dd>`,
|
|
1919
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.provenance.continuityprovenance", {}, "Continuity Provenance")}</dt><dd>${escapeHtml(continuity.semantics.provenance)}</dd>`
|
|
1920
|
+
] : []),
|
|
1921
|
+
...(ownerAdoption ? [
|
|
1922
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.provenance.ownercontract", {}, "Owner Kit Contract")}</dt><dd>${escapeHtml(ownerAdoption.contract)}@${escapeHtml(ownerAdoption.contractVersion)}</dd>`,
|
|
1923
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.provenance.ownerresolution", {}, "Owner Kit Resolution")}</dt><dd>${escapeHtml(ownerAdoption.semantics.resolution)}</dd>`,
|
|
1924
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.provenance.ownerconfidence", {}, "Owner Kit Confidence")}</dt><dd>${escapeHtml(ownerAdoption.semantics.confidence)}</dd>`,
|
|
1925
|
+
`<dt>${renderProjectUiMessage(portalContext, "portal.provenance.ownerprovenance", {}, "Owner Kit Provenance")}</dt><dd>${escapeHtml(ownerAdoption.semantics.provenance)}</dd>`
|
|
1926
|
+
] : []),
|
|
1927
|
+
"</dl>"
|
|
1928
|
+
].join("");
|
|
1929
|
+
}
|
|
1930
|
+
/** direct members 只通过 explicit symbol relation 收集。Collects direct members only through explicit symbol relations. */
|
|
1931
|
+
function collectProjectEntryMembers(entry, entries) {
|
|
1932
|
+
if (!entry.symbolId) {
|
|
1933
|
+
return [];
|
|
1934
|
+
}
|
|
1935
|
+
return entries
|
|
1936
|
+
.filter((candidate) => candidate.hierarchy?.parentSymbolId === entry.symbolId)
|
|
1937
|
+
.sort(compareProjectNavigationEntries);
|
|
1938
|
+
}
|
|
1939
|
+
/** separate 输出 canonical links;with-parent 输出嵌套完整 topic,并对 cycle 回退 link。Separate mode emits canonical links; with-parent emits nested topics with cycle-safe link fallback. */
|
|
1940
|
+
function renderProjectTopicMembers(members, projectInput, locales, selectedLocale, portalContext, includeMemberBodies, ancestors) {
|
|
1941
|
+
if (members.length === 0) {
|
|
1942
|
+
return "";
|
|
1943
|
+
}
|
|
1944
|
+
if (!includeMemberBodies) {
|
|
1945
|
+
return `<ul class="hia-project-member-list">${members.map((member) => `<li><a href="${escapeHtml(createProjectEntryContentPath(member.id))}#${escapeHtml(member.id)}">${escapeHtml(member.name)}</a></li>`).join("")}</ul>`;
|
|
1946
|
+
}
|
|
1947
|
+
return `<div class="hia-project-member-topics">${members.map((member) => {
|
|
1948
|
+
if (ancestors.has(member.id)) {
|
|
1949
|
+
return `<p><a href="${escapeHtml(createProjectEntryContentPath(member.id))}#${escapeHtml(member.id)}">${escapeHtml(member.name)}</a></p>`;
|
|
1950
|
+
}
|
|
1951
|
+
return [
|
|
1952
|
+
`<details class="hia-project-member-card"><summary><span>${escapeHtml(member.name)}</span> <small>${escapeHtml(member.kind)}</small></summary>`,
|
|
1953
|
+
"<div class=\"hia-project-member-card-body\">",
|
|
1954
|
+
renderProjectSemanticTopicInternal(member, projectInput, locales, selectedLocale, portalContext, true, ancestors),
|
|
1955
|
+
"</div></details>"
|
|
1956
|
+
].join("");
|
|
1957
|
+
}).join("")}</div>`;
|
|
1958
|
+
}
|
|
1959
|
+
/** inheritance/implements 与 project relation graph 都只进入 relations section。Inheritance, implements, and project graph edges appear only in the relations section. */
|
|
1960
|
+
function renderProjectTopicRelations(entry, relationGraph, portalContext) {
|
|
1961
|
+
const semanticItems = [
|
|
1962
|
+
...(entry.hierarchy?.baseTypeIds ?? []).map((id) => `<li><span class="hia-kind">${renderProjectUiMessage(portalContext, "portal.relation.inherits", {}, "inherits")}</span> ${escapeHtml(id)}</li>`),
|
|
1963
|
+
...(entry.hierarchy?.interfaceIds ?? []).map((id) => `<li><span class="hia-kind">${renderProjectUiMessage(portalContext, "portal.relation.implements", {}, "implements")}</span> ${escapeHtml(id)}</li>`)
|
|
1964
|
+
];
|
|
1965
|
+
const entryNodeIds = new Set(relationGraph?.nodes.filter((node) => node.entryId === entry.id).map((node) => node.id) ?? []);
|
|
1966
|
+
const graphItems = relationGraph?.relations
|
|
1967
|
+
.filter((relation) => relation.entryId === entry.id || entryNodeIds.has(relation.from) || entryNodeIds.has(relation.to))
|
|
1968
|
+
.map((relation) => `<li><span class="hia-kind">${escapeHtml(relation.kind)}</span> ${escapeHtml(relation.label)}</li>`) ?? [];
|
|
1969
|
+
const items = [...semanticItems, ...graphItems].join("");
|
|
1970
|
+
return items ? `<ul class="hia-project-relation-list">${items}</ul>` : "";
|
|
1971
|
+
}
|
|
1972
|
+
/** source 与 doc-source-map 保持既有 privacy policy;本函数不新增 source body。Source and doc-source-map retain the existing privacy policy; this function adds no source body. */
|
|
1973
|
+
function renderProjectTopicSource(entry, portalContext) {
|
|
1974
|
+
return [
|
|
1975
|
+
entry.source ? renderProjectEntrySource(entry.source, false, portalContext) : "",
|
|
1976
|
+
entry.sourceUsability ? renderProjectEntrySourceUsability(entry.sourceUsability, false, portalContext) : "",
|
|
1977
|
+
entry.docSourceMap ? renderProjectEntryDocSourceMap(entry.docSourceMap, false, portalContext) : "",
|
|
1978
|
+
entry.sourceCommentProjection && portalContext.sourceCommentProjection
|
|
1979
|
+
? renderProjectSourceCommentProjection(entry.sourceCommentProjection, portalContext.sourceCommentProjection, portalContext)
|
|
1980
|
+
: ""
|
|
1981
|
+
].join("");
|
|
1982
|
+
}
|
|
1983
|
+
/**
|
|
1984
|
+
* @lang zh-CN
|
|
1985
|
+
* 将 source-comment projection 缩减为 navigation allowlist;正文与 producer 的正文授权事实都不进入 index。
|
|
1986
|
+
*
|
|
1987
|
+
* @lang en
|
|
1988
|
+
* Reduces a source-comment projection to a navigation allowlist; neither bodies nor the producer body-authorization fact enters the index.
|
|
1989
|
+
*/
|
|
1990
|
+
function selectProjectSourceCommentProjection(projection) {
|
|
1991
|
+
return {
|
|
1992
|
+
contract: projection.contract,
|
|
1993
|
+
contractVersion: projection.contractVersion,
|
|
1994
|
+
defaultLocale: projection.defaultLocale,
|
|
1995
|
+
entryCount: projection.entries.length,
|
|
1996
|
+
privacy: {
|
|
1997
|
+
projectedCommentTextIncluded: false,
|
|
1998
|
+
rawCommentIncluded: false,
|
|
1999
|
+
sourceBodyIncluded: false,
|
|
2000
|
+
sourcesContentPolicy: "none"
|
|
2001
|
+
},
|
|
2002
|
+
projectionId: projection.projectionId,
|
|
2003
|
+
requestedLocale: projection.requestedLocale,
|
|
2004
|
+
resolvedCount: projection.entries.filter((entry) => entry.resolution !== "missing").length,
|
|
2005
|
+
status: projection.status
|
|
2006
|
+
};
|
|
2007
|
+
}
|
|
2008
|
+
/**
|
|
2009
|
+
* @lang zh-CN
|
|
2010
|
+
* 渲染 metadata 与可选纯文本正文。正文必须同时得到 producer projection 与 renderer config 授权。
|
|
2011
|
+
*
|
|
2012
|
+
* @lang en
|
|
2013
|
+
* Renders metadata and optional plain-text bodies. Bodies require authorization from both the producer projection and renderer config.
|
|
2014
|
+
*/
|
|
2015
|
+
function renderProjectSourceCommentProjection(projection, options, portalContext) {
|
|
2016
|
+
const bodyAuthorized = options.contentPolicy === "explicit-projected-text"
|
|
2017
|
+
&& projection.contentPolicy === "explicit-projected-text"
|
|
2018
|
+
&& projection.privacy.projectedCommentTextIncluded;
|
|
2019
|
+
const metadata = [
|
|
2020
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.commentcontract", "Comment Contract")}</dt><dd>${escapeHtml(`${projection.contract}@${projection.contractVersion}`)}</dd>`,
|
|
2021
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.commentlocale", "Comment Locale")}</dt><dd>${escapeHtml(projection.requestedLocale)}</dd>`,
|
|
2022
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.commentstatus", "Comment Status")}</dt><dd>${escapeHtml(projection.status)}</dd>`,
|
|
2023
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.commententries", "Comment Entries")}</dt><dd>${escapeHtml(String(projection.entries.length))}</dd>`,
|
|
2024
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.contentpolicy", "Source Content Policy")}</dt><dd>${escapeHtml(projection.privacy.sourcesContentPolicy)}</dd>`
|
|
2025
|
+
].join("");
|
|
2026
|
+
const entries = projection.entries.map((entry) => {
|
|
2027
|
+
const range = entry.range
|
|
2028
|
+
? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.range", "Range")}</dt><dd>${escapeHtml(`${entry.range.start.line}:${entry.range.start.column}-${entry.range.end.line}:${entry.range.end.column}`)}</dd>`
|
|
2029
|
+
: "";
|
|
2030
|
+
const body = bodyAuthorized && entry.projectedText !== undefined
|
|
2031
|
+
? `<pre class="hia-source-comment"><code>${escapeHtml(entry.projectedText)}</code></pre>`
|
|
2032
|
+
: "";
|
|
2033
|
+
return [
|
|
2034
|
+
`<article class="hia-source-comment-entry" data-hia-source-comment-id="${escapeHtml(entry.commentId)}">`,
|
|
2035
|
+
`<dl class="hia-project-meta"><dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.comment", "Comment")}</dt><dd>${escapeHtml(entry.commentId)}</dd>`,
|
|
2036
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.resolution", "Resolution")}</dt><dd>${escapeHtml(entry.resolution)}</dd>`,
|
|
2037
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.confidence", "Confidence")}</dt><dd>${escapeHtml(entry.confidence)}</dd>`,
|
|
2038
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.section.provenance", "Provenance")}</dt><dd>${escapeHtml(entry.provenance.kind)}</dd>${range}</dl>`,
|
|
2039
|
+
body,
|
|
2040
|
+
"</article>"
|
|
2041
|
+
].join("");
|
|
2042
|
+
}).join("");
|
|
2043
|
+
return `<section class="hia-source-section hia-source-comment-section"><dl class="hia-project-meta">${metadata}</dl>${entries}</section>`;
|
|
2044
|
+
}
|
|
2045
|
+
/** topic diagnostics 使用已有 structured diagnostic,空集合不输出。Topic diagnostics reuse structured diagnostics and omit an empty set. */
|
|
2046
|
+
function renderProjectTopicDiagnostics(diagnostics) {
|
|
2047
|
+
if (diagnostics.length === 0) {
|
|
2048
|
+
return "";
|
|
2049
|
+
}
|
|
2050
|
+
return `<ul>${diagnostics.map((diagnostic) => `<li>${escapeHtml(diagnostic.severity)}:${escapeHtml(diagnostic.code)} - ${escapeHtml(diagnostic.message)}</li>`).join("")}</ul>`;
|
|
2051
|
+
}
|
|
829
2052
|
function renderProjectEntryHierarchy(hierarchy) {
|
|
830
2053
|
const details = [
|
|
831
2054
|
hierarchy.assembly ? `<dt>Assembly</dt><dd>${escapeHtml(hierarchy.assembly)}</dd>` : "",
|
|
@@ -842,15 +2065,9 @@ function renderProjectEntryHierarchy(hierarchy) {
|
|
|
842
2065
|
].join("");
|
|
843
2066
|
return details ? `<dl class="hia-project-meta hia-project-hierarchy-meta">${details}</dl>` : "";
|
|
844
2067
|
}
|
|
2068
|
+
/** @lang zh-CN 仅选择主描述字段,使用原字段身份及共用的locale/fallback规则;不改写i18n模型。 @lang en Selects only the primary prose field with its original identity and shared locale/fallback rules, without rewriting the i18n model. */
|
|
845
2069
|
function renderProjectEntrySummary(entry, locales, selectedLocale) {
|
|
846
|
-
|
|
847
|
-
if (!field && !entry.summary) {
|
|
848
|
-
return "";
|
|
849
|
-
}
|
|
850
|
-
const blocks = locales
|
|
851
|
-
.map((locale) => renderLocalizedBlock(field, locale, selectedLocale, createI18nResolveOptionsFromModel(entry.i18n), entry.summary ?? ""))
|
|
852
|
-
.join("");
|
|
853
|
-
return `<div class="hia-localized-set" data-hia-i18n-field="description">${blocks}</div>`;
|
|
2070
|
+
return renderI18nField(entry, getPrimaryI18nFieldPath(entry), locales, selectedLocale, entry.summary ?? "");
|
|
854
2071
|
}
|
|
855
2072
|
function renderProjectEntryInput(input) {
|
|
856
2073
|
const details = [
|
|
@@ -866,61 +2083,123 @@ function renderProjectEntryProfile(profile) {
|
|
|
866
2083
|
const version = profile.profileVersion ? `@${profile.profileVersion}` : "";
|
|
867
2084
|
return `<p class="hia-project-profile">Profile ${escapeHtml(profile.profileId)}${escapeHtml(version)}</p>`;
|
|
868
2085
|
}
|
|
869
|
-
function renderProjectEntrySource(source) {
|
|
2086
|
+
function renderProjectEntrySource(source, includeHeading = true, portalContext) {
|
|
870
2087
|
const range = source.range ? `:${source.range.start.line}${source.range.end ? `-${source.range.end.line}` : ""}` : "";
|
|
871
2088
|
const label = `${source.path}${range}`;
|
|
872
2089
|
const sourceLabel = source.linkUrl
|
|
873
2090
|
? `<a href="${escapeHtml(source.linkUrl)}">${escapeHtml(label)}</a>`
|
|
874
2091
|
: escapeHtml(label);
|
|
875
2092
|
const sourceDetails = [
|
|
876
|
-
`<dt
|
|
877
|
-
source.language ? `<dt
|
|
878
|
-
source.rangeSource ? `<dt
|
|
879
|
-
source.confidence ? `<dt
|
|
2093
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.section.source", "Source")}</dt><dd>${sourceLabel}</dd>`,
|
|
2094
|
+
source.language ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.language", "Language")}</dt><dd>${escapeHtml(source.language)}</dd>` : "",
|
|
2095
|
+
source.rangeSource ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.rangesource", "Range Source")}</dt><dd>${escapeHtml(source.rangeSource)}</dd>` : "",
|
|
2096
|
+
source.confidence ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.confidence", "Confidence")}</dt><dd>${escapeHtml(source.confidence)}</dd>` : ""
|
|
880
2097
|
].join("");
|
|
881
|
-
const preview = source.preview ? renderProjectSourcePreview(source.preview, source.path) : "";
|
|
882
|
-
const fetchPreview = source.fetchUrl ? renderProjectSourceFetch(source) : "";
|
|
883
|
-
|
|
2098
|
+
const preview = source.preview ? renderProjectSourcePreview(source.preview, source.path, portalContext) : "";
|
|
2099
|
+
const fetchPreview = source.fetchUrl ? renderProjectSourceFetch(source, portalContext) : "";
|
|
2100
|
+
const heading = includeHeading ? `<h3>${renderOptionalProjectUiMessage(portalContext, "portal.section.source", "Source")}</h3>` : "";
|
|
2101
|
+
return `<section class="hia-source-section">${heading}<dl class="hia-project-meta">${sourceDetails}</dl>${preview}${fetchPreview}</section>`;
|
|
884
2102
|
}
|
|
885
|
-
|
|
2103
|
+
/**
|
|
2104
|
+
* @lang zh-CN 只渲染 source-usability allowlist metadata,不生成 link、fetch request、preview 或 source body。
|
|
2105
|
+
* @lang en Renders only allowlisted source-usability metadata and creates no link, fetch request, preview, or source body.
|
|
2106
|
+
*/
|
|
2107
|
+
function renderProjectEntrySourceUsability(sourceUsability, includeHeading = true, portalContext) {
|
|
2108
|
+
const projectIdentity = sourceUsability.projectIdentity;
|
|
2109
|
+
const details = [
|
|
2110
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.resolution", "Resolution")}</dt><dd>${escapeHtml(sourceUsability.resolution)}</dd>`,
|
|
2111
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.confidence", "Confidence")}</dt><dd>${escapeHtml(sourceUsability.confidence)}</dd>`,
|
|
2112
|
+
projectIdentity ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.project", "Project")}</dt><dd>${escapeHtml(projectIdentity.path)}</dd>` : "",
|
|
2113
|
+
projectIdentity ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.projectidentity", "Project Identity")}</dt><dd>${escapeHtml(projectIdentity.id)}</dd>` : "",
|
|
2114
|
+
projectIdentity ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.identitypolicy", "Identity Policy")}</dt><dd>${escapeHtml(projectIdentity.policy)}</dd>` : "",
|
|
2115
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.section.provenance", "Provenance")}</dt><dd>${escapeHtml(`${sourceUsability.provenance.producer}:${sourceUsability.provenance.activity}`)}</dd>`,
|
|
2116
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.contentpolicy", "Source Content Policy")}</dt><dd>${escapeHtml(sourceUsability.privacy.sourcesContentPolicy)}</dd>`
|
|
2117
|
+
].join("");
|
|
2118
|
+
const heading = includeHeading ? `<h3>${renderOptionalProjectUiMessage(portalContext, "portal.source.usability", "Source Usability")}</h3>` : "";
|
|
2119
|
+
return `<section class="hia-source-section hia-source-usability-section">${heading}<dl class="hia-project-meta">${details}</dl></section>`;
|
|
2120
|
+
}
|
|
2121
|
+
/**
|
|
2122
|
+
* @lang zh-CN 将 runtime source-usability 输入收窄为 navigation index allowlist,额外字段不会跨越 privacy boundary。
|
|
2123
|
+
* @lang en Narrows runtime source-usability input to the navigation-index allowlist so extra fields cannot cross the privacy boundary.
|
|
2124
|
+
*/
|
|
2125
|
+
function selectProjectSourceUsability(sourceUsability) {
|
|
2126
|
+
return {
|
|
2127
|
+
relationId: sourceUsability.relationId,
|
|
2128
|
+
resolution: sourceUsability.resolution,
|
|
2129
|
+
confidence: sourceUsability.confidence,
|
|
2130
|
+
provenance: {
|
|
2131
|
+
producer: sourceUsability.provenance.producer,
|
|
2132
|
+
activity: sourceUsability.provenance.activity,
|
|
2133
|
+
contract: sourceUsability.provenance.contract,
|
|
2134
|
+
contractVersion: sourceUsability.provenance.contractVersion
|
|
2135
|
+
},
|
|
2136
|
+
...(sourceUsability.projectIdentity
|
|
2137
|
+
? {
|
|
2138
|
+
projectIdentity: {
|
|
2139
|
+
id: sourceUsability.projectIdentity.id,
|
|
2140
|
+
path: sourceUsability.projectIdentity.path,
|
|
2141
|
+
policy: sourceUsability.projectIdentity.policy
|
|
2142
|
+
}
|
|
2143
|
+
}
|
|
2144
|
+
: {}),
|
|
2145
|
+
privacy: {
|
|
2146
|
+
sourcesContentPolicy: "none",
|
|
2147
|
+
sourcePreviewPolicy: "none",
|
|
2148
|
+
embedsSourcesContent: false
|
|
2149
|
+
}
|
|
2150
|
+
};
|
|
2151
|
+
}
|
|
2152
|
+
/**
|
|
2153
|
+
* @lang zh-CN 渲染一个只接受同源 publicAsset metadata 的源码 reader;缺少授权 asset 时不产生 fallback UI。
|
|
2154
|
+
* @lang en Renders a source reader that accepts same-origin public-asset metadata only and emits no fallback UI when authorization is absent.
|
|
2155
|
+
*
|
|
2156
|
+
* @param source - 已经 source policy 处理的 body-free source reference。Body-free source reference already processed by source policy.
|
|
2157
|
+
* @returns native details reader HTML;拒绝时为空字符串。Native details-reader HTML, or an empty string when refused.
|
|
2158
|
+
*/
|
|
2159
|
+
function renderProjectSourceFetch(source, portalContext) {
|
|
2160
|
+
const publicAsset = source.publicAsset;
|
|
2161
|
+
if (!publicAsset || !source.fetchUrl) {
|
|
2162
|
+
return "";
|
|
2163
|
+
}
|
|
886
2164
|
const startLine = source.range?.start.line ?? 1;
|
|
887
2165
|
const endLine = source.range?.end?.line;
|
|
888
2166
|
const fetchTrigger = source.fetchTrigger ?? "on-expand";
|
|
889
2167
|
const maxLines = source.fetchMaxLines ?? 400;
|
|
890
2168
|
const caption = endLine ? `${source.path}:${startLine}-${endLine}` : `${source.path}:${startLine}`;
|
|
891
|
-
const endAttribute = endLine ? ` data-hia-source-end="${escapeHtml(String(endLine))}"` : "";
|
|
892
2169
|
const manualButton = fetchTrigger === "manual"
|
|
893
|
-
?
|
|
2170
|
+
? `<button type="button" class="hia-source-fetch-button" data-hia-source-fetch-button>${renderOptionalProjectUiMessage(portalContext, "portal.source.load", "Load source / 加载源码")}</button>`
|
|
894
2171
|
: "";
|
|
895
2172
|
return [
|
|
896
|
-
`<details class="hia-source-preview hia-project-source-preview" data-hia-source-fetch="${escapeHtml(source.fetchUrl
|
|
2173
|
+
`<details class="hia-source-preview hia-project-source-preview" data-hia-source-fetch="${escapeHtml(source.fetchUrl)}" data-hia-source-fetch-trigger="${escapeHtml(fetchTrigger)}" data-hia-source-state="idle" data-hia-source-asset-id="${escapeHtml(publicAsset.assetId)}" data-hia-source-integrity="${escapeHtml(publicAsset.digest)}" data-hia-source-byte-length="${escapeHtml(String(publicAsset.byteLength))}" data-hia-source-max-bytes="1048576" data-hia-source-max-lines="${escapeHtml(String(maxLines))}" data-hia-source-timeout="10000">`,
|
|
897
2174
|
`<summary>${escapeHtml(caption)}</summary>`,
|
|
898
2175
|
manualButton,
|
|
899
|
-
|
|
2176
|
+
`<p class="hia-project-loading" data-hia-source-fetch-status role="status" aria-live="polite"${portalContext?.uiLocaleAdoption ? " data-hia-ui-message=\"portal.source.status.loading\"" : ""} hidden></p>`,
|
|
900
2177
|
`<pre class="hia-source-code"><code data-language="${escapeHtml(source.language ?? "")}"></code></pre>`,
|
|
2178
|
+
`<button type="button" class="hia-source-reset-button" data-hia-source-reset hidden>${renderOptionalProjectUiMessage(portalContext, "portal.source.reset", "Reset / 重置")}</button>`,
|
|
901
2179
|
"</details>"
|
|
902
2180
|
].join("");
|
|
903
2181
|
}
|
|
904
|
-
function renderProjectEntryDocSourceMap(docSourceMap) {
|
|
2182
|
+
function renderProjectEntryDocSourceMap(docSourceMap, includeHeading = true, portalContext) {
|
|
905
2183
|
const sourceRange = docSourceMap.sourceRange ? `:${docSourceMap.sourceRange.start.line}${docSourceMap.sourceRange.end ? `-${docSourceMap.sourceRange.end.line}` : ""}` : "";
|
|
906
2184
|
const diagnostics = docSourceMap.diagnostics && docSourceMap.diagnostics.length > 0
|
|
907
|
-
? `<dt
|
|
2185
|
+
? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.diagnostics", "Diagnostics")}</dt><dd>${escapeHtml(docSourceMap.diagnostics.join(", "))}</dd>`
|
|
908
2186
|
: "";
|
|
909
2187
|
const details = [
|
|
910
|
-
`<dt
|
|
911
|
-
`<dt
|
|
912
|
-
docSourceMap.sourcePath ? `<dt
|
|
913
|
-
docSourceMap.sourceRangeSource ? `<dt
|
|
914
|
-
docSourceMap.sourceConfidence ? `<dt
|
|
915
|
-
docSourceMap.artifactPath ? `<dt
|
|
916
|
-
docSourceMap.artifactSelector ? `<dt
|
|
917
|
-
docSourceMap.artifactConfidence ? `<dt
|
|
2188
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.manifest", "Manifest")}</dt><dd>${escapeHtml(docSourceMap.path)}</dd>`,
|
|
2189
|
+
`<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.entry", "Entry")}</dt><dd>${escapeHtml(docSourceMap.entryId)}</dd>`,
|
|
2190
|
+
docSourceMap.sourcePath ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.original", "Original Source")}</dt><dd>${escapeHtml(docSourceMap.sourcePath)}${escapeHtml(sourceRange)}</dd>` : "",
|
|
2191
|
+
docSourceMap.sourceRangeSource ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.rangesource", "Range Source")}</dt><dd>${escapeHtml(docSourceMap.sourceRangeSource)}</dd>` : "",
|
|
2192
|
+
docSourceMap.sourceConfidence ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.sourceconfidence", "Source Confidence")}</dt><dd>${escapeHtml(docSourceMap.sourceConfidence)}</dd>` : "",
|
|
2193
|
+
docSourceMap.artifactPath ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.generatedartifact", "Generated Artifact")}</dt><dd>${escapeHtml(docSourceMap.artifactPath)}</dd>` : "",
|
|
2194
|
+
docSourceMap.artifactSelector ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.selector", "Selector")}</dt><dd>${escapeHtml(docSourceMap.artifactSelector)}</dd>` : "",
|
|
2195
|
+
docSourceMap.artifactConfidence ? `<dt>${renderOptionalProjectUiMessage(portalContext, "portal.source.artifactconfidence", "Artifact Confidence")}</dt><dd>${escapeHtml(docSourceMap.artifactConfidence)}</dd>` : "",
|
|
918
2196
|
diagnostics
|
|
919
2197
|
].join("");
|
|
920
|
-
const actions = renderProjectDocSourceMapOpenRequests(docSourceMap);
|
|
921
|
-
|
|
2198
|
+
const actions = renderProjectDocSourceMapOpenRequests(docSourceMap, portalContext);
|
|
2199
|
+
const heading = includeHeading ? "<h3>Doc Source Map</h3>" : "";
|
|
2200
|
+
return `<section class="hia-source-section">${heading}<dl class="hia-project-meta">${details}</dl>${actions}</section>`;
|
|
922
2201
|
}
|
|
923
|
-
function renderProjectSourcePreview(preview, fallbackPath) {
|
|
2202
|
+
function renderProjectSourcePreview(preview, fallbackPath, portalContext) {
|
|
924
2203
|
if (!preview.content) {
|
|
925
2204
|
return "";
|
|
926
2205
|
}
|
|
@@ -931,22 +2210,22 @@ function renderProjectSourcePreview(preview, fallbackPath) {
|
|
|
931
2210
|
const language = preview.language ? ` data-hia-source-language="${escapeHtml(preview.language)}"` : "";
|
|
932
2211
|
return [
|
|
933
2212
|
`<details class="hia-source-preview hia-project-source-preview"${open}>`,
|
|
934
|
-
`<summary
|
|
2213
|
+
`<summary>${renderOptionalProjectUiMessage(portalContext, "portal.source.preview", `Source Preview ${caption}`, { caption })}</summary>`,
|
|
935
2214
|
`<pre class="hia-source-code"${language}><code>${escapeHtml(preview.content)}</code></pre>`,
|
|
936
2215
|
"</details>"
|
|
937
2216
|
].join("");
|
|
938
2217
|
}
|
|
939
|
-
function renderProjectDocSourceMapOpenRequests(docSourceMap) {
|
|
2218
|
+
function renderProjectDocSourceMapOpenRequests(docSourceMap, portalContext) {
|
|
940
2219
|
const sourceLabel = docSourceMap.sourcePath && docSourceMap.sourceRange
|
|
941
2220
|
? `${docSourceMap.sourcePath}:${docSourceMap.sourceRange.start.line}${docSourceMap.sourceRange.start.column ? `:${docSourceMap.sourceRange.start.column}` : ""}`
|
|
942
2221
|
: docSourceMap.sourcePath;
|
|
943
2222
|
const generatedLabel = docSourceMap.artifactPath ?? "";
|
|
944
2223
|
const buttons = [
|
|
945
2224
|
sourceLabel
|
|
946
|
-
? `<button type="button" data-hia-open-request="source" data-hia-open-path="${escapeHtml(docSourceMap.sourcePath ?? "")}" data-hia-open-line="${escapeHtml(String(docSourceMap.sourceRange?.start.line ?? ""))}" data-hia-open-column="${escapeHtml(String(docSourceMap.sourceRange?.start.column ?? ""))}"
|
|
2225
|
+
? `<button type="button" data-hia-open-request="source" data-hia-open-path="${escapeHtml(docSourceMap.sourcePath ?? "")}" data-hia-open-line="${escapeHtml(String(docSourceMap.sourceRange?.start.line ?? ""))}" data-hia-open-column="${escapeHtml(String(docSourceMap.sourceRange?.start.column ?? ""))}">${renderOptionalProjectUiMessage(portalContext, "portal.source.opensource", `Open Source ${sourceLabel}`, { target: sourceLabel })}</button>`
|
|
947
2226
|
: "",
|
|
948
2227
|
generatedLabel
|
|
949
|
-
? `<button type="button" data-hia-open-request="generated" data-hia-open-path="${escapeHtml(generatedLabel)}"
|
|
2228
|
+
? `<button type="button" data-hia-open-request="generated" data-hia-open-path="${escapeHtml(generatedLabel)}">${renderOptionalProjectUiMessage(portalContext, "portal.source.opengenerated", `Open Generated ${generatedLabel}`, { target: generatedLabel })}</button>`
|
|
950
2229
|
: ""
|
|
951
2230
|
].filter(Boolean).join("");
|
|
952
2231
|
return buttons ? `<div class="hia-source-actions">${buttons}</div>` : "";
|
|
@@ -986,6 +2265,60 @@ function renderProjectDocSourceMaps(docSourceMaps) {
|
|
|
986
2265
|
.join("");
|
|
987
2266
|
return `<section class="hia-project-summary"><h2>Doc Source Maps</h2><ul>${items}</ul></section>`;
|
|
988
2267
|
}
|
|
2268
|
+
/**
|
|
2269
|
+
* 中文:渲染由 source-linkage index 产生的一对多 generated binding 只读关系。
|
|
2270
|
+
* English: Renders the read-only one-to-many generated-binding relation created
|
|
2271
|
+
* by the source-linkage index.
|
|
2272
|
+
*
|
|
2273
|
+
* @remarks
|
|
2274
|
+
* 中文:这里不回读 sidecar、不展开 source body,也不显示 locals/digest;页面只显示
|
|
2275
|
+
* 安全投影里的 source intent、受限 member path、实例键状态、targets 与质量维度。
|
|
2276
|
+
* English: This renderer does not read a sidecar back, expand source bodies, or
|
|
2277
|
+
* display locals/digests; it shows only safe source intent, restricted member
|
|
2278
|
+
* paths, instance-key state, targets, and quality dimensions.
|
|
2279
|
+
*/
|
|
2280
|
+
function renderProjectGeneratedDocumentationBindingProjection(projection, portalContext) {
|
|
2281
|
+
if (!projection) {
|
|
2282
|
+
return "";
|
|
2283
|
+
}
|
|
2284
|
+
const summaryItems = [
|
|
2285
|
+
`<li><span>${renderOptionalProjectUiMessage(portalContext, "portal.binding.bindings", "Bindings / 绑定")}</span><strong>${escapeHtml(String(projection.summary.bindingCount))}</strong></li>`,
|
|
2286
|
+
`<li><span>${renderOptionalProjectUiMessage(portalContext, "portal.binding.expansions", "Expansions / 展开")}</span><strong>${escapeHtml(String(projection.summary.expansionCount))}</strong></li>`,
|
|
2287
|
+
`<li><span>${renderOptionalProjectUiMessage(portalContext, "portal.binding.targets", "Targets / 目标")}</span><strong>${escapeHtml(String(projection.summary.targetCount))}</strong></li>`,
|
|
2288
|
+
`<li><span>${renderOptionalProjectUiMessage(portalContext, "portal.binding.diagnostics", "Diagnostics / 诊断")}</span><strong>${escapeHtml(String(projection.summary.diagnosticCount))}</strong></li>`,
|
|
2289
|
+
`<li><span>sourcesContent</span><strong>${escapeHtml(projection.privacy.sourcesContentPolicy)}</strong></li>`
|
|
2290
|
+
].join("");
|
|
2291
|
+
const bindings = projection.bindings.map((binding) => {
|
|
2292
|
+
const memberPath = binding.bindingRef.memberPath.join(".") || binding.bindingRef.rootDeclarationId;
|
|
2293
|
+
const quality = `${binding.quality.resolutionKind} / ${binding.quality.confidence} / ${binding.quality.provenanceCoverage}`;
|
|
2294
|
+
const expansions = binding.expansions
|
|
2295
|
+
.map((expansion) => {
|
|
2296
|
+
const key = expansion.instanceKey.displayKey ?? expansion.instanceKey.status;
|
|
2297
|
+
return `<li>${escapeHtml(expansion.id)} · key=${escapeHtml(key)} · ${escapeHtml(expansion.quality.resolutionKind)} / ${escapeHtml(expansion.quality.confidence)} / ${escapeHtml(expansion.quality.provenanceCoverage)} · ${renderOptionalProjectUiMessage(portalContext, "portal.binding.targetcount", `${expansion.targetIds.length} target(s)`, { count: expansion.targetIds.length })}</li>`;
|
|
2298
|
+
})
|
|
2299
|
+
.join("");
|
|
2300
|
+
const targets = binding.targets
|
|
2301
|
+
.map((target) => `<li>${escapeHtml(target.id)} · ${escapeHtml(target.identity.kind)}${target.identity.selector ? ` · ${escapeHtml(target.identity.selector)}` : ""}</li>`)
|
|
2302
|
+
.join("");
|
|
2303
|
+
return [
|
|
2304
|
+
"<li>",
|
|
2305
|
+
`<strong>${escapeHtml(binding.id)}</strong>`,
|
|
2306
|
+
`<p>${escapeHtml(binding.sourceIntent.kind)}${binding.sourceIntent.field ? ` / ${escapeHtml(binding.sourceIntent.field)}` : ""} · ${escapeHtml(memberPath)} · ${escapeHtml(quality)}</p>`,
|
|
2307
|
+
`<p>scope=${escapeHtml(binding.scopeId)} · ${escapeHtml(binding.composition.relation)} / ${escapeHtml(binding.composition.mergePolicy)}</p>`,
|
|
2308
|
+
expansions ? `<details><summary>${renderOptionalProjectUiMessage(portalContext, "portal.binding.expansions", "Expansions / 展开")} (${escapeHtml(String(binding.expansions.length))})</summary><ul>${expansions}</ul></details>` : "",
|
|
2309
|
+
targets ? `<details><summary>${renderOptionalProjectUiMessage(portalContext, "portal.binding.targets", "Targets / 目标")} (${escapeHtml(String(binding.targets.length))})</summary><ul>${targets}</ul></details>` : "",
|
|
2310
|
+
"</li>"
|
|
2311
|
+
].join("");
|
|
2312
|
+
}).join("");
|
|
2313
|
+
return [
|
|
2314
|
+
"<section class=\"hia-project-summary hia-generated-binding-relations\">",
|
|
2315
|
+
`<h2>${renderOptionalProjectUiMessage(portalContext, "portal.binding.heading", "Generated Documentation Bindings / 生成式文档绑定")}</h2>`,
|
|
2316
|
+
`<p>${escapeHtml(projection.contract)}@${escapeHtml(projection.contractVersion)} · ${escapeHtml(projection.status)}</p>`,
|
|
2317
|
+
`<ul class=\"hia-project-group-list\">${summaryItems}</ul>`,
|
|
2318
|
+
bindings ? `<ul class=\"hia-project-relation-list\">${bindings}</ul>` : `<p>${renderOptionalProjectUiMessage(portalContext, "portal.binding.none", "No binding relations available.")}</p>`,
|
|
2319
|
+
"</section>"
|
|
2320
|
+
].join("");
|
|
2321
|
+
}
|
|
989
2322
|
function renderProjectRelationGraphSummary(relationGraph) {
|
|
990
2323
|
if (!relationGraph || relationGraph.relationCount === 0) {
|
|
991
2324
|
return "";
|
|
@@ -1280,7 +2613,7 @@ function collectProjectNavigationGroups(entries) {
|
|
|
1280
2613
|
...collectProjectNavigationGroupsBy(entries, "source-root", (entry) => getProjectSourceRoot(entry.source?.path))
|
|
1281
2614
|
].sort(compareProjectNavigationGroups);
|
|
1282
2615
|
}
|
|
1283
|
-
function collectProjectNavigationTree(entries) {
|
|
2616
|
+
function collectProjectNavigationTree(entries, informationArchitecture) {
|
|
1284
2617
|
return PROJECT_VIEW_ORDER
|
|
1285
2618
|
.filter((view) => view !== "all")
|
|
1286
2619
|
.flatMap((view) => {
|
|
@@ -1288,9 +2621,11 @@ function collectProjectNavigationTree(entries) {
|
|
|
1288
2621
|
if (viewEntries.length === 0) {
|
|
1289
2622
|
return [];
|
|
1290
2623
|
}
|
|
1291
|
-
const children =
|
|
1292
|
-
?
|
|
1293
|
-
:
|
|
2624
|
+
const children = informationArchitecture
|
|
2625
|
+
? collectManifestSemanticNavigationTree(viewEntries, view)
|
|
2626
|
+
: view === "dotnet"
|
|
2627
|
+
? collectDotNetNavigationTree(viewEntries)
|
|
2628
|
+
: collectSemanticSourceNavigationTree(viewEntries);
|
|
1294
2629
|
return [{
|
|
1295
2630
|
id: `view:${view}`,
|
|
1296
2631
|
kind: "view",
|
|
@@ -1301,7 +2636,7 @@ function collectProjectNavigationTree(entries) {
|
|
|
1301
2636
|
}];
|
|
1302
2637
|
});
|
|
1303
2638
|
}
|
|
1304
|
-
function collectDotNetNavigationTree(entries) {
|
|
2639
|
+
function collectDotNetNavigationTree(entries, includeTypeRelations = true) {
|
|
1305
2640
|
const roots = new Map();
|
|
1306
2641
|
for (const entry of entries) {
|
|
1307
2642
|
const parts = getDotNetNavigationParts(entry);
|
|
@@ -1327,7 +2662,7 @@ function collectDotNetNavigationTree(entries) {
|
|
|
1327
2662
|
if (isDotNetTypeNavigationEntry(entry)) {
|
|
1328
2663
|
typeNode.entryId = entry.id;
|
|
1329
2664
|
assignProjectTreeEntryRefs(typeNode, entry);
|
|
1330
|
-
if (entry.kind === "dotnet-type") {
|
|
2665
|
+
if (includeTypeRelations && entry.kind === "dotnet-type") {
|
|
1331
2666
|
addDotNetInheritanceNodes(typeNode, entry);
|
|
1332
2667
|
}
|
|
1333
2668
|
continue;
|
|
@@ -1340,6 +2675,125 @@ function collectDotNetNavigationTree(entries) {
|
|
|
1340
2675
|
}
|
|
1341
2676
|
return sortProjectTreeNodes([...roots.values()].map(finalizeProjectTreeBuilder));
|
|
1342
2677
|
}
|
|
2678
|
+
/**
|
|
2679
|
+
* 构造 manifest-only semantic prefix,再接既有语言 containment;显式 IA 不使用 source path 分组。
|
|
2680
|
+
* Builds a manifest-only semantic prefix followed by language containment; explicit IA never groups by source path.
|
|
2681
|
+
*/
|
|
2682
|
+
function collectManifestSemanticNavigationTree(entries, view) {
|
|
2683
|
+
const semanticRoots = new Map();
|
|
2684
|
+
const groupedEntries = new Map();
|
|
2685
|
+
for (const entry of entries) {
|
|
2686
|
+
assertRenderProjectSemanticPath(entry.semanticPath);
|
|
2687
|
+
const path = entry.semanticPath ?? [];
|
|
2688
|
+
const key = path.length > 0
|
|
2689
|
+
? path.map((segment) => `${segment.kind}:${segment.id}`).join("|")
|
|
2690
|
+
: `unscoped:${view}`;
|
|
2691
|
+
const group = groupedEntries.get(key) ?? { path, entries: [] };
|
|
2692
|
+
group.entries.push(entry);
|
|
2693
|
+
groupedEntries.set(key, group);
|
|
2694
|
+
}
|
|
2695
|
+
const unscopedChildren = [];
|
|
2696
|
+
for (const [groupKey, group] of [...groupedEntries.entries()].sort(([left], [right]) => compareStableText(left, right))) {
|
|
2697
|
+
const languageChildren = view === "dotnet"
|
|
2698
|
+
? collectDotNetNavigationTree(group.entries, false)
|
|
2699
|
+
: collectSymbolContainmentNavigationTree(group.entries);
|
|
2700
|
+
const namespacedChildren = languageChildren.map((node) => namespaceProjectNavigationNode(node, `semantic:${groupKey}`));
|
|
2701
|
+
if (group.path.length === 0) {
|
|
2702
|
+
unscopedChildren.push(...namespacedChildren);
|
|
2703
|
+
continue;
|
|
2704
|
+
}
|
|
2705
|
+
let parentMap = semanticRoots;
|
|
2706
|
+
let parentBuilder;
|
|
2707
|
+
let qualifiedId = "semantic";
|
|
2708
|
+
for (const segment of group.path) {
|
|
2709
|
+
qualifiedId = `${qualifiedId}:${segment.kind}:${segment.id}`;
|
|
2710
|
+
const builder = getOrCreateProjectTreeChild(parentMap, qualifiedId, segment.kind, segment.label);
|
|
2711
|
+
for (const entry of group.entries) {
|
|
2712
|
+
addProjectTreeEntry(builder, entry);
|
|
2713
|
+
}
|
|
2714
|
+
parentBuilder = builder;
|
|
2715
|
+
parentMap = builder.childrenById;
|
|
2716
|
+
}
|
|
2717
|
+
if (parentBuilder) {
|
|
2718
|
+
parentBuilder.terminalChildren.push(...namespacedChildren);
|
|
2719
|
+
}
|
|
2720
|
+
}
|
|
2721
|
+
const semanticChildren = [...semanticRoots.values()].map(finalizeProjectTreeBuilder);
|
|
2722
|
+
return sortProjectTreeNodes([...semanticChildren, ...unscopedChildren]);
|
|
2723
|
+
}
|
|
2724
|
+
/** 非 DotNet 显式 IA 下只使用 symbol containment,不回退到 source-root/source-file。Non-.NET explicit IA uses symbol containment only, without source grouping fallback. */
|
|
2725
|
+
function collectSymbolContainmentNavigationTree(entries) {
|
|
2726
|
+
const roots = new Map();
|
|
2727
|
+
const nodesByEntryId = new Map();
|
|
2728
|
+
const entriesBySymbolId = new Map();
|
|
2729
|
+
for (const entry of entries) {
|
|
2730
|
+
if (entry.symbolId) {
|
|
2731
|
+
entriesBySymbolId.set(entry.symbolId, entry);
|
|
2732
|
+
}
|
|
2733
|
+
const entryNode = getOrCreateProjectTreeChild(nodesByEntryId, `entry:${entry.id}`, isProjectTypeLikeKind(entry.kind) ? "type" : "entry", entry.name);
|
|
2734
|
+
addProjectTreeEntry(entryNode, entry);
|
|
2735
|
+
entryNode.entryId = entry.id;
|
|
2736
|
+
assignProjectTreeEntryRefs(entryNode, entry);
|
|
2737
|
+
}
|
|
2738
|
+
for (const entry of entries) {
|
|
2739
|
+
const entryNode = nodesByEntryId.get(`entry:${entry.id}`);
|
|
2740
|
+
const parentEntry = entry.hierarchy?.parentSymbolId
|
|
2741
|
+
? entriesBySymbolId.get(entry.hierarchy.parentSymbolId)
|
|
2742
|
+
: undefined;
|
|
2743
|
+
const parentNode = parentEntry ? nodesByEntryId.get(`entry:${parentEntry.id}`) : undefined;
|
|
2744
|
+
if (entryNode && parentEntry && parentNode && parentNode !== entryNode) {
|
|
2745
|
+
parentNode.childrenById.set(entryNode.id, entryNode);
|
|
2746
|
+
incrementProjectNavigationAncestorCounts(parentEntry, entriesBySymbolId, nodesByEntryId);
|
|
2747
|
+
}
|
|
2748
|
+
else if (entryNode) {
|
|
2749
|
+
roots.set(entryNode.id, entryNode);
|
|
2750
|
+
}
|
|
2751
|
+
}
|
|
2752
|
+
return sortProjectTreeNodes([...roots.values()].map(finalizeProjectTreeBuilder));
|
|
2753
|
+
}
|
|
2754
|
+
/** 为跨 semantic container 的 shard node id 增加 namespace,entry id 本身保持不变。Namespaces shard node ids across semantic containers while preserving entry identity. */
|
|
2755
|
+
function namespaceProjectNavigationNode(node, namespace) {
|
|
2756
|
+
return {
|
|
2757
|
+
...node,
|
|
2758
|
+
id: `${namespace}:${node.id}`,
|
|
2759
|
+
...(node.children
|
|
2760
|
+
? { children: node.children.map((child) => namespaceProjectNavigationNode(child, namespace)) }
|
|
2761
|
+
: {})
|
|
2762
|
+
};
|
|
2763
|
+
}
|
|
2764
|
+
/** direct renderer API 的 semantic path 同样 fail closed,防止绕过 manifest validator。Semantic paths passed directly to the renderer also fail closed. */
|
|
2765
|
+
function assertRenderProjectSemanticPath(path) {
|
|
2766
|
+
if (!path) {
|
|
2767
|
+
return;
|
|
2768
|
+
}
|
|
2769
|
+
if (!Array.isArray(path) || path.length === 0) {
|
|
2770
|
+
throw new TypeError("HIA_PORTAL_IA_SEMANTIC_PATH_INVALID: semanticPath must be a non-empty array.");
|
|
2771
|
+
}
|
|
2772
|
+
const seen = new Set();
|
|
2773
|
+
for (const segment of path) {
|
|
2774
|
+
const exactSegment = isExactObject(segment, ["kind", "id", "label"]);
|
|
2775
|
+
const normalizedLabel = exactSegment && typeof segment.label === "string"
|
|
2776
|
+
? segment.label.replaceAll("\\", "/")
|
|
2777
|
+
: "";
|
|
2778
|
+
const safeLabel = exactSegment
|
|
2779
|
+
&& Boolean(segment.label)
|
|
2780
|
+
&& segment.label.length <= 160
|
|
2781
|
+
&& !/[\u0000-\u001F\u007F]/u.test(segment.label)
|
|
2782
|
+
&& !normalizedLabel.includes("../")
|
|
2783
|
+
&& normalizedLabel !== ".."
|
|
2784
|
+
&& !normalizedLabel.startsWith("/")
|
|
2785
|
+
&& !/^[A-Za-z]:\//u.test(normalizedLabel)
|
|
2786
|
+
&& !/^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(normalizedLabel);
|
|
2787
|
+
if (!exactSegment
|
|
2788
|
+
|| !DOCUMENTATION_PORTAL_SEMANTIC_PATH_KINDS.includes(segment.kind)
|
|
2789
|
+
|| !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(segment.id)
|
|
2790
|
+
|| !safeLabel
|
|
2791
|
+
|| seen.has(segment.id)) {
|
|
2792
|
+
throw new TypeError("HIA_PORTAL_IA_SEMANTIC_PATH_INVALID: semanticPath must contain unique, public kind/id/label segments.");
|
|
2793
|
+
}
|
|
2794
|
+
seen.add(segment.id);
|
|
2795
|
+
}
|
|
2796
|
+
}
|
|
1343
2797
|
function addDotNetInheritanceNodes(typeNode, entry) {
|
|
1344
2798
|
for (const baseTypeId of entry.hierarchy?.baseTypeIds ?? []) {
|
|
1345
2799
|
const relationNode = getOrCreateProjectTreeChild(typeNode.childrenById, `${typeNode.id}:base:${slugProjectGroupLabel(baseTypeId)}`, "relation", `Base: ${baseTypeId.replace(/^T:/u, "")}`);
|
|
@@ -1428,7 +2882,8 @@ function getOrCreateProjectTreeChild(map, id, kind, label) {
|
|
|
1428
2882
|
entryCount: 0,
|
|
1429
2883
|
views: new Set(),
|
|
1430
2884
|
children: [],
|
|
1431
|
-
childrenById: new Map()
|
|
2885
|
+
childrenById: new Map(),
|
|
2886
|
+
terminalChildren: []
|
|
1432
2887
|
};
|
|
1433
2888
|
map.set(id, created);
|
|
1434
2889
|
return created;
|
|
@@ -1450,7 +2905,10 @@ function assignProjectTreeSourcePath(node, sourcePath) {
|
|
|
1450
2905
|
}
|
|
1451
2906
|
function finalizeProjectTreeBuilder(node) {
|
|
1452
2907
|
const childBuilders = node.childrenById.size > 0 ? [...node.childrenById.values()] : node.children;
|
|
1453
|
-
const children = sortProjectTreeNodes(
|
|
2908
|
+
const children = sortProjectTreeNodes([
|
|
2909
|
+
...childBuilders.map(finalizeProjectTreeBuilder),
|
|
2910
|
+
...node.terminalChildren
|
|
2911
|
+
]);
|
|
1454
2912
|
return {
|
|
1455
2913
|
id: node.id,
|
|
1456
2914
|
kind: node.kind,
|
|
@@ -1476,28 +2934,40 @@ function projectTreeKindOrder(kind) {
|
|
|
1476
2934
|
if (kind === "view") {
|
|
1477
2935
|
return 0;
|
|
1478
2936
|
}
|
|
1479
|
-
if (kind === "
|
|
2937
|
+
if (kind === "repository") {
|
|
2938
|
+
return 1;
|
|
2939
|
+
}
|
|
2940
|
+
if (kind === "package") {
|
|
1480
2941
|
return 2;
|
|
1481
2942
|
}
|
|
1482
|
-
if (kind === "
|
|
2943
|
+
if (kind === "layer") {
|
|
1483
2944
|
return 3;
|
|
1484
2945
|
}
|
|
1485
|
-
if (kind === "
|
|
2946
|
+
if (kind === "contract" || kind === "operation") {
|
|
1486
2947
|
return 4;
|
|
1487
2948
|
}
|
|
1488
|
-
if (kind === "
|
|
2949
|
+
if (kind === "surface" || kind === "project") {
|
|
1489
2950
|
return 5;
|
|
1490
2951
|
}
|
|
1491
2952
|
if (kind === "assembly") {
|
|
1492
|
-
return
|
|
2953
|
+
return 6;
|
|
2954
|
+
}
|
|
2955
|
+
if (kind === "namespace") {
|
|
2956
|
+
return 7;
|
|
2957
|
+
}
|
|
2958
|
+
if (kind === "type") {
|
|
2959
|
+
return 8;
|
|
2960
|
+
}
|
|
2961
|
+
if (kind === "relation") {
|
|
2962
|
+
return 9;
|
|
1493
2963
|
}
|
|
1494
2964
|
if (kind === "source-root") {
|
|
1495
|
-
return
|
|
2965
|
+
return 10;
|
|
1496
2966
|
}
|
|
1497
2967
|
if (kind === "source-file") {
|
|
1498
|
-
return
|
|
2968
|
+
return 11;
|
|
1499
2969
|
}
|
|
1500
|
-
return
|
|
2970
|
+
return 12;
|
|
1501
2971
|
}
|
|
1502
2972
|
function getDotNetNavigationParts(entry) {
|
|
1503
2973
|
const fallback = getDotNetNonAssemblyNavigationParts(entry);
|
|
@@ -1725,8 +3195,10 @@ function renderLocaleControl(locales, selectedLocale) {
|
|
|
1725
3195
|
}
|
|
1726
3196
|
function renderSymbol(symbol, document, locales, selectedLocale) {
|
|
1727
3197
|
const signature = symbol.signature ? `<pre class="hia-signature"><code>${escapeHtml(symbol.signature)}</code></pre>` : "";
|
|
1728
|
-
|
|
1729
|
-
const
|
|
3198
|
+
// <lang><zh-CN>纯.NET summary与description共用主字段选择,主字段只呈现一次,附加字段全部保留。</zh-CN><en>.NET summary and description share primary-field selection, showing the primary once and retaining every additional field.</en></lang>
|
|
3199
|
+
const primaryPath = getPrimaryI18nFieldPath(symbol);
|
|
3200
|
+
const description = renderI18nField(symbol, primaryPath, locales, selectedLocale, symbol.summary);
|
|
3201
|
+
const otherFields = renderAdditionalI18nFields(symbol, locales, selectedLocale, primaryPath);
|
|
1730
3202
|
const source = renderSource(symbol);
|
|
1731
3203
|
return [
|
|
1732
3204
|
`<article class="hia-symbol" id="${escapeHtml(symbol.id)}">`,
|
|
@@ -1739,9 +3211,15 @@ function renderSymbol(symbol, document, locales, selectedLocale) {
|
|
|
1739
3211
|
"</article>"
|
|
1740
3212
|
].join("");
|
|
1741
3213
|
}
|
|
1742
|
-
|
|
3214
|
+
/** @lang zh-CN description优先,其次summary,无模型时仍用description承载普通摘要回退。 @lang en Prefers description, then summary, retaining description for plain-summary fallback without a model. */
|
|
3215
|
+
function getPrimaryI18nFieldPath(owner) {
|
|
3216
|
+
return owner.i18n?.fields.description ? "description" : owner.i18n?.fields.summary ? "summary" : "description";
|
|
3217
|
+
}
|
|
3218
|
+
/** @lang zh-CN 按原顺序遍历所有附加字段;不按.NET字段清单过滤,不修改输入或把字段文本当HTML。 @lang en Iterates all additional fields in input order without a .NET whitelist, input mutation, or interpreting field text as HTML. */
|
|
3219
|
+
function renderAdditionalI18nFields(symbol, locales, selectedLocale, primaryPath = "description") {
|
|
1743
3220
|
const fields = symbol.i18n?.fields || {};
|
|
1744
|
-
|
|
3221
|
+
// <lang><zh-CN>只移除已显示的主字段,允许summary与description同时完整显示。</zh-CN><en>Remove only the already-rendered primary field, allowing summary and description to coexist completely.</en></lang>
|
|
3222
|
+
const fieldEntries = Object.entries(fields).filter(([fieldPath]) => fieldPath !== primaryPath);
|
|
1745
3223
|
if (fieldEntries.length === 0) {
|
|
1746
3224
|
return "";
|
|
1747
3225
|
}
|
|
@@ -1755,13 +3233,18 @@ function renderAdditionalI18nFields(symbol, locales, selectedLocale) {
|
|
|
1755
3233
|
.join("");
|
|
1756
3234
|
return items ? `<section class="hia-i18n-fields"><h3>Localized Fields</h3><dl>${items}</dl></section>` : "";
|
|
1757
3235
|
}
|
|
3236
|
+
/** @lang zh-CN 渲染每个locale的纯文本与明确fallback;所有locale均无正文时省略空字段。 @lang en Renders plain text and explicit fallback per locale, omitting fields with no prose in any locale. */
|
|
1758
3237
|
function renderI18nField(symbol, fieldPath, locales, selectedLocale, fallbackText = "") {
|
|
1759
3238
|
const field = getI18nField(symbol.i18n, fieldPath);
|
|
1760
3239
|
if (!field && !fallbackText) {
|
|
1761
3240
|
return "";
|
|
1762
3241
|
}
|
|
3242
|
+
// <lang><zh-CN>缺译不等于空字段:先用现有解析规则核全部locale,保留任何可解析正文。</zh-CN><en>A missing translation is not an empty field: use existing resolution rules across all locales and retain any resolvable prose.</en></lang>
|
|
3243
|
+
const resolveOptions = createI18nResolveOptions(symbol);
|
|
3244
|
+
if (field && !fallbackText && !locales.some((locale) => resolveI18nFieldText(field, locale, resolveOptions).text.length > 0))
|
|
3245
|
+
return "";
|
|
1763
3246
|
const blocks = locales
|
|
1764
|
-
.map((locale) => renderLocalizedBlock(field, locale, selectedLocale,
|
|
3247
|
+
.map((locale) => renderLocalizedBlock(field, locale, selectedLocale, resolveOptions, fallbackText))
|
|
1765
3248
|
.join("");
|
|
1766
3249
|
return `<div class="hia-localized-set" data-hia-i18n-field="${escapeHtml(fieldPath)}">${blocks}</div>`;
|
|
1767
3250
|
}
|
|
@@ -1777,7 +3260,7 @@ function renderLocalizedBlock(field, locale, selectedLocale, options, fallbackTe
|
|
|
1777
3260
|
? `<span class="hia-fallback-badge">fallback: ${escapeHtml(resolved.resolvedLocale)}</span>`
|
|
1778
3261
|
: "";
|
|
1779
3262
|
return [
|
|
1780
|
-
`<p class="hia-localized-text" data-hia-locale="${escapeHtml(locale)}"${fallbackAttrs}${hidden}>`,
|
|
3263
|
+
`<p class="hia-localized-text" data-hia-locale="${escapeHtml(locale)}" lang="${escapeHtml(locale)}"${fallbackAttrs}${hidden}>`,
|
|
1781
3264
|
escapeHtml(resolved.text),
|
|
1782
3265
|
fallbackBadge,
|
|
1783
3266
|
"</p>"
|
|
@@ -1913,6 +3396,7 @@ function resolveProjectLocaleModel(projectInput, requestedLocale) {
|
|
|
1913
3396
|
}
|
|
1914
3397
|
return { selectedLocale, locales };
|
|
1915
3398
|
}
|
|
3399
|
+
/** @lang zh-CN 从不修改的i18n owner读取默认/fallback语言,保持各渲染路径一致。 @lang en Reads default/fallback locales from an unmodified i18n owner consistently across rendering routes. */
|
|
1916
3400
|
function createI18nResolveOptions(symbol) {
|
|
1917
3401
|
return createI18nResolveOptionsFromModel(symbol.i18n);
|
|
1918
3402
|
}
|