@salesforcedevs/docs-components 1.38.0-alpha.0 → 1.38.0-plv-alpha
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/lwc.config.json +0 -1
- package/package.json +28 -28
- package/src/modules/doc/amfReference/amfReference.html +2 -2
- package/src/modules/doc/amfReference/amfReference.ts +24 -152
- package/src/modules/doc/contentLayout/contentLayout.html +0 -1
- package/src/modules/doc/contentLayout/contentLayout.ts +1 -67
- package/src/modules/doc/lwcContentLayout/lwcContentLayout.html +0 -1
- package/src/modules/doc/redocReference/redocReference.css +1 -0
- package/src/modules/doc/redocReference/redocReference.ts +510 -23
- package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.html +16 -1
- package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.ts +236 -85
- package/src/modules/doc/xmlContent/xmlContent.html +2 -2
- package/src/modules/docUtils/utils/utils.ts +22 -2
- package/src/modules/doc/versionPicker/versionPicker.css +0 -64
- package/src/modules/doc/versionPicker/versionPicker.html +0 -40
- package/src/modules/doc/versionPicker/versionPicker.ts +0 -65
- package/src/modules/docUtils/sidebarLoader/sidebarLoader.ts +0 -50
|
@@ -4,11 +4,37 @@ import DocPhase from "doc/phase";
|
|
|
4
4
|
import DxFooter from "dx/footer";
|
|
5
5
|
import DxIcon from "dx/icon";
|
|
6
6
|
import SidebarFooterNav from "dx/sidebarFooterNav";
|
|
7
|
+
import VersionPicker from "dx/versionPicker";
|
|
7
8
|
import SprigSurvey from "doc/sprigSurvey";
|
|
8
9
|
import { throttle } from "throttle-debounce";
|
|
9
10
|
import { pollUntil } from "dxUtils/async";
|
|
10
11
|
import { toJson } from "dxUtils/normalizers";
|
|
11
|
-
import
|
|
12
|
+
import { oldVersionDocInfo } from "docUtils/utils";
|
|
13
|
+
import {
|
|
14
|
+
applyVersionToHref,
|
|
15
|
+
collectSubtreeCanonicalHrefs,
|
|
16
|
+
DOCS_LOCALE_SEGMENT_INDEX,
|
|
17
|
+
DOCS_PATH_SEGMENT,
|
|
18
|
+
normalizePath,
|
|
19
|
+
getTopicVersionKey,
|
|
20
|
+
hrefMatchesCurrentPage,
|
|
21
|
+
getVersionPickerOptions,
|
|
22
|
+
persistTopicVersion,
|
|
23
|
+
projectHrefForVersion,
|
|
24
|
+
projectVersionForCurrentPage,
|
|
25
|
+
projectVersionKey,
|
|
26
|
+
projectVersionOptions,
|
|
27
|
+
REFERENCES_LOCALE_SEGMENT_INDEX,
|
|
28
|
+
resolveProjectVersion,
|
|
29
|
+
toCanonicalHref,
|
|
30
|
+
toProjectVersionPicker
|
|
31
|
+
} from "dxUtils/topicVersion";
|
|
32
|
+
import type {
|
|
33
|
+
ProjectVersionPicker,
|
|
34
|
+
TopicVersionOption,
|
|
35
|
+
VersionedNode
|
|
36
|
+
} from "dxUtils/topicVersion";
|
|
37
|
+
import type { DocPhaseInfo, OptionWithLink } from "typings/custom";
|
|
12
38
|
|
|
13
39
|
declare global {
|
|
14
40
|
interface Window {
|
|
@@ -33,8 +59,27 @@ type ReferenceItem = {
|
|
|
33
59
|
topic?: ReferenceTopic;
|
|
34
60
|
};
|
|
35
61
|
|
|
62
|
+
/** A selectable spec version. Mirrors `ReferenceVersion` in `doc/amfReference`. */
|
|
63
|
+
type ReferenceVersion = {
|
|
64
|
+
id: string;
|
|
65
|
+
label: string;
|
|
66
|
+
deprecated?: boolean;
|
|
67
|
+
selected?: boolean;
|
|
68
|
+
link: { href: string };
|
|
69
|
+
};
|
|
70
|
+
|
|
36
71
|
type ReferenceConfig = {
|
|
37
72
|
refList: ReferenceItem[];
|
|
73
|
+
versions?: ReferenceVersion[];
|
|
74
|
+
/** Latest switching URL. The sidebar stores the selected version under this key. */
|
|
75
|
+
versionTopicSessionKey?: string;
|
|
76
|
+
};
|
|
77
|
+
|
|
78
|
+
/** `versionedTopicTree`: the spec's versioned topic, plus a project picker when sent. */
|
|
79
|
+
type VersionedTopicTree = {
|
|
80
|
+
topics?: VersionedNode[];
|
|
81
|
+
versions?: TopicVersionOption[];
|
|
82
|
+
versionTopicSessionKey?: string;
|
|
38
83
|
};
|
|
39
84
|
|
|
40
85
|
const SCROLL_THROTTLE_DELAY = 50;
|
|
@@ -42,7 +87,7 @@ const ELEMENT_TIMEOUT = 10000;
|
|
|
42
87
|
const ELEMENT_CHECK_INTERVAL = 100;
|
|
43
88
|
const DEFAULT_PROJECT_TITLE = "All Reference";
|
|
44
89
|
const BACK_TARGET_STORAGE_KEY = "redoc-back-target";
|
|
45
|
-
const
|
|
90
|
+
const SELECTED_VIEW_STORAGE_KEY = "redoc-selected-view";
|
|
46
91
|
const DEFAULT_LOCALE = "en-us";
|
|
47
92
|
|
|
48
93
|
export default class RedocReference extends LightningElement {
|
|
@@ -80,6 +125,7 @@ export default class RedocReference extends LightningElement {
|
|
|
80
125
|
error
|
|
81
126
|
);
|
|
82
127
|
}
|
|
128
|
+
this.refreshVersions();
|
|
83
129
|
}
|
|
84
130
|
|
|
85
131
|
@api
|
|
@@ -116,6 +162,48 @@ export default class RedocReference extends LightningElement {
|
|
|
116
162
|
*/
|
|
117
163
|
@api headerHref: string | null = null;
|
|
118
164
|
|
|
165
|
+
/**
|
|
166
|
+
* Versioned topic that owns this spec, including its children.
|
|
167
|
+
* Href matches this page, so an older version still has its version
|
|
168
|
+
* in the path.
|
|
169
|
+
*/
|
|
170
|
+
@api
|
|
171
|
+
set versionedTopicTree(value: string | VersionedTopicTree | null) {
|
|
172
|
+
try {
|
|
173
|
+
const parsed = toJson(value) as VersionedTopicTree | null;
|
|
174
|
+
this._versionedTopicNode = parsed?.topics?.[0] ?? null;
|
|
175
|
+
this._treeProjectPicker = toProjectVersionPicker(parsed);
|
|
176
|
+
} catch (error) {
|
|
177
|
+
this._versionedTopicNode = null;
|
|
178
|
+
this._treeProjectPicker = undefined;
|
|
179
|
+
}
|
|
180
|
+
this.refreshVersions();
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
get versionedTopicTree(): { topics?: VersionedNode[] } | null {
|
|
184
|
+
return this._versionedTopicNode
|
|
185
|
+
? { topics: [this._versionedTopicNode] }
|
|
186
|
+
: null;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
private _versionedTopicNode: VersionedNode | null = null;
|
|
190
|
+
private _treeProjectPicker: ProjectVersionPicker | undefined;
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* Project-level picker shared with the markdown sidebar. Read from the
|
|
194
|
+
* tree payload when it carries one, else from `referenceConfig`. A spec
|
|
195
|
+
* with its own topic-level versions keeps that picker instead.
|
|
196
|
+
*/
|
|
197
|
+
private get projectPicker(): ProjectVersionPicker | undefined {
|
|
198
|
+
if (this._treeProjectPicker) {
|
|
199
|
+
return this._treeProjectPicker;
|
|
200
|
+
}
|
|
201
|
+
if (this._versionedTopicNode?.versions?.length) {
|
|
202
|
+
return undefined;
|
|
203
|
+
}
|
|
204
|
+
return toProjectVersionPicker(this._referenceConfig);
|
|
205
|
+
}
|
|
206
|
+
|
|
119
207
|
@api
|
|
120
208
|
get contentType(): string {
|
|
121
209
|
return this._contentType;
|
|
@@ -152,6 +240,96 @@ export default class RedocReference extends LightningElement {
|
|
|
152
240
|
return refCount > 1;
|
|
153
241
|
}
|
|
154
242
|
|
|
243
|
+
private _versions: ReferenceVersion[] = [];
|
|
244
|
+
|
|
245
|
+
get versions(): ReferenceVersion[] {
|
|
246
|
+
return this._versions;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/**
|
|
250
|
+
* Picker hrefs for the open page. Both setters call this because LWC can
|
|
251
|
+
* assign referenceConfig and versionedTopicTree in either order. The page
|
|
252
|
+
* URL is already set by then and does not change for this instance.
|
|
253
|
+
*/
|
|
254
|
+
private refreshVersions(): void {
|
|
255
|
+
// Project options already point at this spec in every version.
|
|
256
|
+
const projectPicker = this.projectPicker;
|
|
257
|
+
if (projectPicker) {
|
|
258
|
+
this._versions = (projectVersionOptions(projectPicker) ??
|
|
259
|
+
[]) as ReferenceVersion[];
|
|
260
|
+
return;
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
const versions = this._referenceConfig?.versions ?? [];
|
|
264
|
+
const node = this._versionedTopicNode;
|
|
265
|
+
if (!node?.versions?.length || typeof window === "undefined") {
|
|
266
|
+
this._versions = versions;
|
|
267
|
+
return;
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
// Same helper as the markdown sidebar. The same array means this page
|
|
271
|
+
// is outside the topic, so the backend switching URLs stay as authored.
|
|
272
|
+
const rewritten = getVersionPickerOptions(node);
|
|
273
|
+
if (!rewritten || rewritten === node.versions) {
|
|
274
|
+
this._versions = versions;
|
|
275
|
+
return;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
this._versions = versions.map((version) => {
|
|
279
|
+
const href = rewritten.find((option) => option.id === version.id)
|
|
280
|
+
?.link?.href;
|
|
281
|
+
if (!href || href === version.link?.href) {
|
|
282
|
+
return version;
|
|
283
|
+
}
|
|
284
|
+
return {
|
|
285
|
+
...version,
|
|
286
|
+
link: { ...version.link, href }
|
|
287
|
+
};
|
|
288
|
+
});
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
/**
|
|
292
|
+
* Project versions: the open URL, then the project session, then
|
|
293
|
+
* `selected`, matching the markdown sidebar. Otherwise the version
|
|
294
|
+
* flagged `selected`, else the first (the latest/GA version).
|
|
295
|
+
*/
|
|
296
|
+
get selectedVersion(): ReferenceVersion | null {
|
|
297
|
+
const versions = this.versions;
|
|
298
|
+
const projectPicker = this.projectPicker;
|
|
299
|
+
if (projectPicker) {
|
|
300
|
+
const resolved = resolveProjectVersion(
|
|
301
|
+
projectPicker,
|
|
302
|
+
this.language ?? undefined
|
|
303
|
+
);
|
|
304
|
+
return versions.find((v) => v.id === resolved?.id) ?? null;
|
|
305
|
+
}
|
|
306
|
+
return versions.find((v) => v.selected) ?? versions[0] ?? null;
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
/** True when the selected version is the latest/GA one (index 0). */
|
|
310
|
+
get latestVersion(): boolean {
|
|
311
|
+
return this.versions.length
|
|
312
|
+
? this.selectedVersion?.id === this.versions[0].id
|
|
313
|
+
: false;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
get hasVersionPicker(): boolean {
|
|
317
|
+
return this.versions.length > 0;
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/** "Newer version available" banner info when on a non-latest version, else null. */
|
|
321
|
+
private get oldVersionInfo(): DocPhaseInfo | null {
|
|
322
|
+
if (this.versions.length > 1 && !this.latestVersion) {
|
|
323
|
+
return oldVersionDocInfo(this.versions[0].link.href);
|
|
324
|
+
}
|
|
325
|
+
return null;
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** A single version has nothing to choose, so it renders read-only. */
|
|
329
|
+
get isVersionReadOnly(): boolean {
|
|
330
|
+
return this.versions.length === 1;
|
|
331
|
+
}
|
|
332
|
+
|
|
155
333
|
// Reads stored back target
|
|
156
334
|
private getBackTargetFromSession(): string | null {
|
|
157
335
|
return sessionStorage.getItem(BACK_TARGET_STORAGE_KEY);
|
|
@@ -186,13 +364,104 @@ export default class RedocReference extends LightningElement {
|
|
|
186
364
|
private onBackClick = (event: Event): void => {
|
|
187
365
|
event.preventDefault();
|
|
188
366
|
|
|
189
|
-
const target = this.
|
|
367
|
+
const target = this.getVersionedBackTarget() ?? this.headerHref;
|
|
190
368
|
|
|
191
369
|
if (target) {
|
|
192
370
|
window.location.assign(target);
|
|
193
371
|
}
|
|
194
372
|
};
|
|
195
373
|
|
|
374
|
+
/**
|
|
375
|
+
* When the back target is in this spec's topic, return it on the
|
|
376
|
+
* selected version. With no back target, do the same for the header
|
|
377
|
+
* link when that link is the versioned parent.
|
|
378
|
+
*/
|
|
379
|
+
private getVersionedBackTarget(): string | null {
|
|
380
|
+
const stored = this.getTranslatedBackTarget();
|
|
381
|
+
const selectedVersion = this.selectedVersion;
|
|
382
|
+
const target = stored ?? this.headerHref;
|
|
383
|
+
if (!target || !selectedVersion) {
|
|
384
|
+
return stored;
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
let targetUrl: URL;
|
|
388
|
+
try {
|
|
389
|
+
targetUrl = new URL(target, window.location.origin);
|
|
390
|
+
} catch {
|
|
391
|
+
return target;
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
// Project versions cover every page in the project, so any project
|
|
395
|
+
// page goes back on the selected version, like a topic family does
|
|
396
|
+
// below. Otherwise the stored page keeps the version it was opened
|
|
397
|
+
// on and the markdown sidebar switches back to it.
|
|
398
|
+
const projectPicker = this.projectPicker;
|
|
399
|
+
if (projectPicker) {
|
|
400
|
+
const versioned = projectHrefForVersion(
|
|
401
|
+
targetUrl.pathname,
|
|
402
|
+
projectPicker,
|
|
403
|
+
selectedVersion.id
|
|
404
|
+
);
|
|
405
|
+
return versioned
|
|
406
|
+
? `${versioned}${targetUrl.search}${targetUrl.hash}`
|
|
407
|
+
: target;
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
// The spec picker links can use a different file name in each version
|
|
411
|
+
// (`sample-api` and `new-sample-api`). That pair cannot move a sibling
|
|
412
|
+
// page between versions. The parent topic's switching URLs share one
|
|
413
|
+
// slug, so the back target is rewritten from those.
|
|
414
|
+
const rewriteVersions = this.backTargetVersions();
|
|
415
|
+
const rewriteVersion =
|
|
416
|
+
rewriteVersions.find(
|
|
417
|
+
(version) => version.id === selectedVersion.id
|
|
418
|
+
) ?? selectedVersion;
|
|
419
|
+
const familyHrefs = this._versionedTopicNode
|
|
420
|
+
? collectSubtreeCanonicalHrefs(this._versionedTopicNode).map(
|
|
421
|
+
(href) => toCanonicalHref(href, rewriteVersions)
|
|
422
|
+
)
|
|
423
|
+
: [];
|
|
424
|
+
|
|
425
|
+
const canonicalTarget = toCanonicalHref(
|
|
426
|
+
targetUrl.pathname,
|
|
427
|
+
rewriteVersions
|
|
428
|
+
);
|
|
429
|
+
const inFamily = familyHrefs.some(
|
|
430
|
+
(href) => normalizePath(href) === normalizePath(canonicalTarget)
|
|
431
|
+
);
|
|
432
|
+
if (!inFamily) {
|
|
433
|
+
return target;
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
const versioned = applyVersionToHref(
|
|
437
|
+
canonicalTarget,
|
|
438
|
+
rewriteVersion,
|
|
439
|
+
rewriteVersions
|
|
440
|
+
);
|
|
441
|
+
if (!versioned) {
|
|
442
|
+
return target;
|
|
443
|
+
}
|
|
444
|
+
return `${versioned}${targetUrl.search}${targetUrl.hash}`;
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
/**
|
|
448
|
+
* Version URLs used to move the back target. Prefer the parent topic's
|
|
449
|
+
* switching URLs. Fall back to the spec picker when this spec is the
|
|
450
|
+
* versioned topic itself.
|
|
451
|
+
*/
|
|
452
|
+
private backTargetVersions(): ReferenceVersion[] {
|
|
453
|
+
const familyVersions = this._versionedTopicNode?.versions;
|
|
454
|
+
if (!familyVersions?.length) {
|
|
455
|
+
return this.versions;
|
|
456
|
+
}
|
|
457
|
+
return familyVersions.map((version) => ({
|
|
458
|
+
id: version.id,
|
|
459
|
+
label: version.label,
|
|
460
|
+
link: { href: version.link?.href ?? "" },
|
|
461
|
+
selected: version.id === this.selectedVersion?.id
|
|
462
|
+
}));
|
|
463
|
+
}
|
|
464
|
+
|
|
196
465
|
private getTranslatedBackTarget(): string | null {
|
|
197
466
|
const stored = this.getBackTargetFromSession();
|
|
198
467
|
if (stored) {
|
|
@@ -202,7 +471,9 @@ export default class RedocReference extends LightningElement {
|
|
|
202
471
|
}
|
|
203
472
|
|
|
204
473
|
const referrer = this.getSameOriginReferrerHref();
|
|
205
|
-
return referrer &&
|
|
474
|
+
return referrer &&
|
|
475
|
+
!this.isLocaleHref(new URL(referrer).pathname) &&
|
|
476
|
+
!this.isVersionHref(new URL(referrer).pathname)
|
|
206
477
|
? referrer
|
|
207
478
|
: null;
|
|
208
479
|
}
|
|
@@ -216,7 +487,9 @@ export default class RedocReference extends LightningElement {
|
|
|
216
487
|
const segments = url.pathname.split("/").filter(Boolean);
|
|
217
488
|
|
|
218
489
|
// docs -> right after "docs"; references -> after the product segment.
|
|
219
|
-
const localeIndex = this.isDocContentType
|
|
490
|
+
const localeIndex = this.isDocContentType
|
|
491
|
+
? DOCS_LOCALE_SEGMENT_INDEX
|
|
492
|
+
: REFERENCES_LOCALE_SEGMENT_INDEX;
|
|
220
493
|
|
|
221
494
|
if (segments[0] === DOCS_PATH_SEGMENT) {
|
|
222
495
|
// Drop the existing locale segment, if any
|
|
@@ -241,7 +514,10 @@ export default class RedocReference extends LightningElement {
|
|
|
241
514
|
}
|
|
242
515
|
|
|
243
516
|
const referrerUrl = new URL(referrerHref);
|
|
244
|
-
if (
|
|
517
|
+
if (
|
|
518
|
+
this.isLocaleHref(referrerUrl.pathname) ||
|
|
519
|
+
this.isVersionHref(referrerUrl.pathname)
|
|
520
|
+
) {
|
|
245
521
|
return;
|
|
246
522
|
}
|
|
247
523
|
|
|
@@ -282,6 +558,19 @@ export default class RedocReference extends LightningElement {
|
|
|
282
558
|
});
|
|
283
559
|
}
|
|
284
560
|
|
|
561
|
+
/**
|
|
562
|
+
* switching version on this same page.
|
|
563
|
+
*/
|
|
564
|
+
private isVersionHref(pathname: string): boolean {
|
|
565
|
+
return this.versions.some((version) => {
|
|
566
|
+
const href = version?.link?.href;
|
|
567
|
+
return (
|
|
568
|
+
!!href &&
|
|
569
|
+
new URL(href, window.location.origin).pathname === pathname
|
|
570
|
+
);
|
|
571
|
+
});
|
|
572
|
+
}
|
|
573
|
+
|
|
285
574
|
/** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
|
|
286
575
|
get effectiveFooterOrigin(): string {
|
|
287
576
|
return (
|
|
@@ -297,6 +586,17 @@ export default class RedocReference extends LightningElement {
|
|
|
297
586
|
// Track the back target, preserving it across locale switches
|
|
298
587
|
this.trackBackTarget();
|
|
299
588
|
|
|
589
|
+
// Remember the selected version for the sidebar. Changing version
|
|
590
|
+
// reloads this page. A project picker stores only a version the URL
|
|
591
|
+
// names, so it never overwrites the reader's choice with a fallback.
|
|
592
|
+
const topicKey = this.getParentTopicVersionKey();
|
|
593
|
+
const versionToStore = this.projectPicker
|
|
594
|
+
? projectVersionForCurrentPage(this.projectPicker)
|
|
595
|
+
: this.selectedVersion;
|
|
596
|
+
if (topicKey && versionToStore) {
|
|
597
|
+
persistTopicVersion(topicKey, versionToStore.id);
|
|
598
|
+
}
|
|
599
|
+
|
|
300
600
|
window.addEventListener("scroll", this.handleScrollAndResize);
|
|
301
601
|
window.addEventListener("resize", this.handleScrollAndResize);
|
|
302
602
|
}
|
|
@@ -309,6 +609,7 @@ export default class RedocReference extends LightningElement {
|
|
|
309
609
|
}
|
|
310
610
|
|
|
311
611
|
disconnectedCallback(): void {
|
|
612
|
+
this.bindViewLatestLink(null);
|
|
312
613
|
window.removeEventListener("scroll", this.handleScrollAndResize);
|
|
313
614
|
window.removeEventListener("resize", this.handleScrollAndResize);
|
|
314
615
|
|
|
@@ -354,6 +655,14 @@ export default class RedocReference extends LightningElement {
|
|
|
354
655
|
return parseInt(value, 10) || 0;
|
|
355
656
|
}
|
|
356
657
|
|
|
658
|
+
/** Redoc's LNB background color, themeable via `--doc-c-redoc-sidebar-bg`. */
|
|
659
|
+
private get sidebarBackgroundColor(): string {
|
|
660
|
+
const value = getComputedStyle(this.template.host).getPropertyValue(
|
|
661
|
+
"--doc-c-redoc-sidebar-bg"
|
|
662
|
+
);
|
|
663
|
+
return value.trim() || "white";
|
|
664
|
+
}
|
|
665
|
+
|
|
357
666
|
/*
|
|
358
667
|
** Since we could not use --dx-g-global-header-height as getPropertyValue returns a calc expression,
|
|
359
668
|
** we are using the respective CSS variables to calculate the height.
|
|
@@ -469,7 +778,14 @@ export default class RedocReference extends LightningElement {
|
|
|
469
778
|
specUrl,
|
|
470
779
|
{
|
|
471
780
|
// Dynamic scroll offset to account for headers
|
|
472
|
-
scrollYOffset: this.calculateScrollYOffset
|
|
781
|
+
scrollYOffset: this.calculateScrollYOffset,
|
|
782
|
+
// Redoc's own styled background outranks injected
|
|
783
|
+
// CSS, so the LNB background must be set via theme.
|
|
784
|
+
theme: {
|
|
785
|
+
sidebar: {
|
|
786
|
+
backgroundColor: this.sidebarBackgroundColor
|
|
787
|
+
}
|
|
788
|
+
}
|
|
473
789
|
},
|
|
474
790
|
redocContainer,
|
|
475
791
|
(error: any) => {
|
|
@@ -515,10 +831,7 @@ export default class RedocReference extends LightningElement {
|
|
|
515
831
|
const apiContentDiv = await this.waitForApiContent(redocContainer);
|
|
516
832
|
apiContentDiv.setAttribute("lwc:dom", "manual");
|
|
517
833
|
|
|
518
|
-
|
|
519
|
-
if (docPhaseInfo) {
|
|
520
|
-
this.insertDocPhase(apiContentDiv, docPhaseInfo);
|
|
521
|
-
}
|
|
834
|
+
this.insertStatusItems(apiContentDiv);
|
|
522
835
|
|
|
523
836
|
this.appendFooterItems(apiContentDiv);
|
|
524
837
|
|
|
@@ -527,10 +840,22 @@ export default class RedocReference extends LightningElement {
|
|
|
527
840
|
|
|
528
841
|
// Wait for footer to be rendered before updating styles
|
|
529
842
|
requestAnimationFrame(() => {
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
843
|
+
try {
|
|
844
|
+
this.updateRedocThirdColumnStyle(redocContainer);
|
|
845
|
+
|
|
846
|
+
// Restore the view selected before a version switch only
|
|
847
|
+
// after all layout mutations (footer, header) are
|
|
848
|
+
// complete, so the scroll lands on the correct element.
|
|
849
|
+
this.restoreSelectedView();
|
|
850
|
+
|
|
851
|
+
// Fix initial hash scroll after doc phase insertion
|
|
852
|
+
this.handleInitialHashScrollFix();
|
|
853
|
+
} catch (error) {
|
|
854
|
+
this.showErrorUI(
|
|
855
|
+
"Failed to integrate custom components:",
|
|
856
|
+
error
|
|
857
|
+
);
|
|
858
|
+
}
|
|
534
859
|
});
|
|
535
860
|
} catch (error) {
|
|
536
861
|
this.showErrorUI("Failed to integrate custom components:", error);
|
|
@@ -560,6 +885,127 @@ export default class RedocReference extends LightningElement {
|
|
|
560
885
|
}
|
|
561
886
|
}
|
|
562
887
|
|
|
888
|
+
/** Builds the version picker DOM by reusing `dx-version-picker`. */
|
|
889
|
+
private buildVersionPickerDom(): HTMLElement {
|
|
890
|
+
const wrapper = document.createElement("div");
|
|
891
|
+
wrapper.className = "redoc-version-picker";
|
|
892
|
+
|
|
893
|
+
const picker = createElement("dx-version-picker", {
|
|
894
|
+
is: VersionPicker
|
|
895
|
+
});
|
|
896
|
+
|
|
897
|
+
Object.assign(picker, {
|
|
898
|
+
versions: this.versions,
|
|
899
|
+
selectedVersion: this.selectedVersion,
|
|
900
|
+
latestVersion: this.latestVersion,
|
|
901
|
+
readOnly: this.isVersionReadOnly
|
|
902
|
+
});
|
|
903
|
+
picker.addEventListener("change", this.onVersionChange);
|
|
904
|
+
wrapper.appendChild(picker);
|
|
905
|
+
|
|
906
|
+
return wrapper;
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
/**
|
|
910
|
+
* Key the sidebar uses for this topic's selected version.
|
|
911
|
+
* Missing `versionTopicSessionKey` returns null so nothing is written.
|
|
912
|
+
*/
|
|
913
|
+
private getParentTopicVersionKey(): string | null {
|
|
914
|
+
const projectPicker = this.projectPicker;
|
|
915
|
+
if (projectPicker) {
|
|
916
|
+
return (
|
|
917
|
+
projectVersionKey(projectPicker, this.language ?? undefined) ||
|
|
918
|
+
null
|
|
919
|
+
);
|
|
920
|
+
}
|
|
921
|
+
const versionTopicSessionKey =
|
|
922
|
+
this._referenceConfig?.versionTopicSessionKey;
|
|
923
|
+
if (!versionTopicSessionKey) {
|
|
924
|
+
return null;
|
|
925
|
+
}
|
|
926
|
+
return (
|
|
927
|
+
getTopicVersionKey(
|
|
928
|
+
{ name: versionTopicSessionKey },
|
|
929
|
+
this.language ?? undefined
|
|
930
|
+
) || null
|
|
931
|
+
);
|
|
932
|
+
}
|
|
933
|
+
|
|
934
|
+
/**
|
|
935
|
+
* Stashes the current view (URL hash) before the version link navigates.
|
|
936
|
+
* A project version is also stored for the project and opened by href,
|
|
937
|
+
* so the markdown sidebar shows the same version afterwards.
|
|
938
|
+
*/
|
|
939
|
+
private onVersionChange = (event?: CustomEvent): void => {
|
|
940
|
+
sessionStorage.setItem(
|
|
941
|
+
SELECTED_VIEW_STORAGE_KEY,
|
|
942
|
+
window.location.hash || ""
|
|
943
|
+
);
|
|
944
|
+
if (!this.projectPicker) {
|
|
945
|
+
return;
|
|
946
|
+
}
|
|
947
|
+
const versionId = event?.detail ? String(event.detail) : "";
|
|
948
|
+
const option = this.versions.find((v) => v.id === versionId);
|
|
949
|
+
const topicKey = this.getParentTopicVersionKey();
|
|
950
|
+
if (!option || !topicKey) {
|
|
951
|
+
return;
|
|
952
|
+
}
|
|
953
|
+
persistTopicVersion(topicKey, option.id);
|
|
954
|
+
const href = option.link?.href;
|
|
955
|
+
if (href && !hrefMatchesCurrentPage(href)) {
|
|
956
|
+
window.location.assign(href);
|
|
957
|
+
}
|
|
958
|
+
};
|
|
959
|
+
|
|
960
|
+
private _viewLatestAnchor: HTMLAnchorElement | null = null;
|
|
961
|
+
|
|
962
|
+
/**
|
|
963
|
+
* View Latest is innerHTML inside the banner's doc-phase. For a project
|
|
964
|
+
* picker, store the latest id before leaving so every page in the project
|
|
965
|
+
* opens on latest.
|
|
966
|
+
*/
|
|
967
|
+
private bindViewLatestLink(anchor: HTMLAnchorElement | null): void {
|
|
968
|
+
if (this._viewLatestAnchor === anchor) {
|
|
969
|
+
return;
|
|
970
|
+
}
|
|
971
|
+
this._viewLatestAnchor?.removeEventListener(
|
|
972
|
+
"click",
|
|
973
|
+
this.handleViewLatestClick
|
|
974
|
+
);
|
|
975
|
+
this._viewLatestAnchor = anchor;
|
|
976
|
+
anchor?.addEventListener("click", this.handleViewLatestClick);
|
|
977
|
+
}
|
|
978
|
+
|
|
979
|
+
private handleViewLatestClick = (event: Event): void => {
|
|
980
|
+
const latest = this.versions[0];
|
|
981
|
+
const topicKey = this.getParentTopicVersionKey();
|
|
982
|
+
const href = (event.currentTarget as HTMLAnchorElement | null)?.href;
|
|
983
|
+
if (!latest || !topicKey || !href) {
|
|
984
|
+
return;
|
|
985
|
+
}
|
|
986
|
+
event.preventDefault();
|
|
987
|
+
persistTopicVersion(topicKey, latest.id);
|
|
988
|
+
window.location.assign(href);
|
|
989
|
+
};
|
|
990
|
+
|
|
991
|
+
/**
|
|
992
|
+
* Re-applies the view stashed before a version switch, if its anchor exists
|
|
993
|
+
* in the new spec; otherwise a no-op (lands on the spec root).
|
|
994
|
+
*/
|
|
995
|
+
private restoreSelectedView(): void {
|
|
996
|
+
const storedHash = sessionStorage.getItem(SELECTED_VIEW_STORAGE_KEY);
|
|
997
|
+
sessionStorage.removeItem(SELECTED_VIEW_STORAGE_KEY);
|
|
998
|
+
|
|
999
|
+
if (!storedHash || window.location.hash) {
|
|
1000
|
+
return;
|
|
1001
|
+
}
|
|
1002
|
+
|
|
1003
|
+
const targetId = storedHash.replace(/^#/, "");
|
|
1004
|
+
if (targetId && document.getElementById(targetId)) {
|
|
1005
|
+
window.location.hash = storedHash;
|
|
1006
|
+
}
|
|
1007
|
+
}
|
|
1008
|
+
|
|
563
1009
|
/**
|
|
564
1010
|
* Builds the locale picker DOM by reusing `dx-sidebar-footer-nav`
|
|
565
1011
|
*/
|
|
@@ -581,12 +1027,17 @@ export default class RedocReference extends LightningElement {
|
|
|
581
1027
|
}
|
|
582
1028
|
|
|
583
1029
|
/**
|
|
584
|
-
* Builds a
|
|
1030
|
+
* Builds the doc header: a title group (back link + spec title) and, when
|
|
1031
|
+
* versions are available, the version picker as a sibling row. Layout/gaps
|
|
1032
|
+
* are styled by the developer-website's redoc CSS.
|
|
585
1033
|
*/
|
|
586
1034
|
private buildProjectHeaderDom(): HTMLElement {
|
|
587
1035
|
const wrapper = document.createElement("div");
|
|
588
1036
|
wrapper.className = "redoc-project-header";
|
|
589
1037
|
|
|
1038
|
+
const main = document.createElement("div");
|
|
1039
|
+
main.className = "redoc-project-header-main";
|
|
1040
|
+
|
|
590
1041
|
if (this.projectTitle) {
|
|
591
1042
|
const backLink = document.createElement("a");
|
|
592
1043
|
backLink.className = "redoc-project-back";
|
|
@@ -607,14 +1058,20 @@ export default class RedocReference extends LightningElement {
|
|
|
607
1058
|
|
|
608
1059
|
backLink.appendChild(icon);
|
|
609
1060
|
backLink.appendChild(label);
|
|
610
|
-
|
|
1061
|
+
main.appendChild(backLink);
|
|
611
1062
|
}
|
|
612
1063
|
|
|
613
1064
|
if (this.specTitle) {
|
|
614
1065
|
const specEl = document.createElement("h2");
|
|
615
1066
|
specEl.className = "redoc-spec-title dx-text-display-7";
|
|
616
1067
|
specEl.textContent = this.specTitle;
|
|
617
|
-
|
|
1068
|
+
main.appendChild(specEl);
|
|
1069
|
+
}
|
|
1070
|
+
|
|
1071
|
+
wrapper.appendChild(main);
|
|
1072
|
+
|
|
1073
|
+
if (this.hasVersionPicker) {
|
|
1074
|
+
wrapper.appendChild(this.buildVersionPickerDom());
|
|
618
1075
|
}
|
|
619
1076
|
|
|
620
1077
|
return wrapper;
|
|
@@ -639,15 +1096,45 @@ export default class RedocReference extends LightningElement {
|
|
|
639
1096
|
return container.querySelector<HTMLElement>(".api-content")!;
|
|
640
1097
|
}
|
|
641
1098
|
|
|
642
|
-
//
|
|
643
|
-
|
|
1099
|
+
// Inserts the doc phase and, on a non-latest version, a dismissible
|
|
1100
|
+
// "newer version" banner into a shared doc-phase-wrapper at container start
|
|
1101
|
+
private insertStatusItems(container: HTMLElement): void {
|
|
1102
|
+
const docPhaseInfo = this.getDocPhaseInfo();
|
|
1103
|
+
const oldVersionInfo = this.oldVersionInfo;
|
|
1104
|
+
if (!docPhaseInfo && !oldVersionInfo) {
|
|
1105
|
+
return;
|
|
1106
|
+
}
|
|
1107
|
+
|
|
644
1108
|
const wrapper = document.createElement("div");
|
|
645
1109
|
wrapper.className = "doc-phase-wrapper";
|
|
646
1110
|
container.insertBefore(wrapper, container.firstChild);
|
|
647
1111
|
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
1112
|
+
if (docPhaseInfo) {
|
|
1113
|
+
const docPhaseElement = createElement("doc-phase", {
|
|
1114
|
+
is: DocPhase
|
|
1115
|
+
});
|
|
1116
|
+
Object.assign(docPhaseElement, { docPhaseInfo });
|
|
1117
|
+
wrapper.appendChild(docPhaseElement);
|
|
1118
|
+
}
|
|
1119
|
+
|
|
1120
|
+
if (oldVersionInfo) {
|
|
1121
|
+
const versionBanner = createElement("doc-phase", { is: DocPhase });
|
|
1122
|
+
Object.assign(versionBanner, {
|
|
1123
|
+
docPhaseInfo: oldVersionInfo,
|
|
1124
|
+
dismissible: true,
|
|
1125
|
+
iconName: "warning"
|
|
1126
|
+
});
|
|
1127
|
+
versionBanner.addEventListener("dismissphase", () => {
|
|
1128
|
+
versionBanner.remove();
|
|
1129
|
+
this.updateSidebarPosition();
|
|
1130
|
+
});
|
|
1131
|
+
wrapper.appendChild(versionBanner);
|
|
1132
|
+
if (this.projectPicker) {
|
|
1133
|
+
this.bindViewLatestLink(
|
|
1134
|
+
versionBanner.shadowRoot?.querySelector("a") ?? null
|
|
1135
|
+
);
|
|
1136
|
+
}
|
|
1137
|
+
}
|
|
651
1138
|
}
|
|
652
1139
|
|
|
653
1140
|
// Appends footer component to container
|