@salesforcedevs/docs-components 1.35.0-final-test → 1.35.0-node24-1

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 CHANGED
@@ -26,6 +26,7 @@
26
26
  "doc/phase",
27
27
  "doc/redocReference",
28
28
  "doc/specificationContent",
29
+ "doc/versionPicker",
29
30
  "doc/xmlContent",
30
31
  "docUtils/searchClient",
31
32
  "docUtils/searchController",
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@salesforcedevs/docs-components",
3
- "version": "1.35.0-final-test",
3
+ "version": "1.35.0-node24-1",
4
4
  "description": "Docs Lightning web components for DSC",
5
5
  "license": "MIT",
6
6
  "main": "index.js",
7
7
  "engines": {
8
- "node": "22.x"
8
+ "node": "24.x"
9
9
  },
10
10
  "publishConfig": {
11
11
  "access": "public"
@@ -25,5 +25,6 @@
25
25
  "@types/lodash.orderby": "4.6.9",
26
26
  "@types/lodash.uniqby": "4.7.9"
27
27
  },
28
- "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
28
+ "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad",
29
+ "stableVersion": "1.35.0"
29
30
  }
@@ -35,13 +35,13 @@
35
35
  ondismissphase={handleDismissVersionBanner}
36
36
  ></doc-phase>
37
37
  <div lwc:if={isVersionEnabled} slot="sidebar-header">
38
- <dx-version-picker
38
+ <doc-version-picker
39
39
  onchange={handleVersionChange}
40
40
  data-type="version"
41
41
  versions={versions}
42
42
  selected-version={selectedVersion}
43
43
  latest-version={latestVersion}
44
- ></dx-version-picker>
44
+ ></doc-version-picker>
45
45
  </div>
46
46
  <template lwc:if={showSpecBasedReference}>
47
47
  <div class="container">
@@ -3,5 +3,4 @@
3
3
  --doc-c-redoc-sidebar-top: calc(
4
4
  var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
5
5
  );
6
- --doc-c-redoc-sidebar-bg: white;
7
6
  }
@@ -4,26 +4,11 @@ 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";
8
7
  import SprigSurvey from "doc/sprigSurvey";
9
8
  import { throttle } from "throttle-debounce";
10
9
  import { pollUntil } from "dxUtils/async";
11
10
  import { toJson } from "dxUtils/normalizers";
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
- getVersionPickerOptions,
21
- persistTopicVersion,
22
- REFERENCES_LOCALE_SEGMENT_INDEX,
23
- toCanonicalHref
24
- } from "dxUtils/topicVersion";
25
- import type { VersionedNode } from "dxUtils/topicVersion";
26
- import type { DocPhaseInfo, OptionWithLink } from "typings/custom";
11
+ import type { OptionWithLink } from "typings/custom";
27
12
 
28
13
  declare global {
29
14
  interface Window {
@@ -48,20 +33,8 @@ type ReferenceItem = {
48
33
  topic?: ReferenceTopic;
49
34
  };
50
35
 
51
- /** A selectable spec version. Mirrors `ReferenceVersion` in `doc/amfReference`. */
52
- type ReferenceVersion = {
53
- id: string;
54
- label: string;
55
- deprecated?: boolean;
56
- selected?: boolean;
57
- link: { href: string };
58
- };
59
-
60
36
  type ReferenceConfig = {
61
37
  refList: ReferenceItem[];
62
- versions?: ReferenceVersion[];
63
- /** Latest switching URL. The sidebar stores the selected version under this key. */
64
- versionTopicSessionKey?: string;
65
38
  };
66
39
 
67
40
  const SCROLL_THROTTLE_DELAY = 50;
@@ -69,7 +42,7 @@ const ELEMENT_TIMEOUT = 10000;
69
42
  const ELEMENT_CHECK_INTERVAL = 100;
70
43
  const DEFAULT_PROJECT_TITLE = "All Reference";
71
44
  const BACK_TARGET_STORAGE_KEY = "redoc-back-target";
72
- const SELECTED_VIEW_STORAGE_KEY = "redoc-selected-view";
45
+ const DOCS_PATH_SEGMENT = "docs";
73
46
  const DEFAULT_LOCALE = "en-us";
74
47
 
75
48
  export default class RedocReference extends LightningElement {
@@ -107,7 +80,6 @@ export default class RedocReference extends LightningElement {
107
80
  error
108
81
  );
109
82
  }
110
- this.refreshVersions();
111
83
  }
112
84
 
113
85
  @api
@@ -144,32 +116,6 @@ export default class RedocReference extends LightningElement {
144
116
  */
145
117
  @api headerHref: string | null = null;
146
118
 
147
- /**
148
- * Versioned topic that owns this spec, including its children.
149
- * Href matches this page, so an older version still has its version
150
- * in the path.
151
- */
152
- @api
153
- set versionedTopicTree(
154
- value: string | { topics?: VersionedNode[] } | null
155
- ) {
156
- try {
157
- const parsed = toJson(value) as { topics?: VersionedNode[] } | null;
158
- this._versionedTopicNode = parsed?.topics?.[0] ?? null;
159
- } catch (error) {
160
- this._versionedTopicNode = null;
161
- }
162
- this.refreshVersions();
163
- }
164
-
165
- get versionedTopicTree(): { topics?: VersionedNode[] } | null {
166
- return this._versionedTopicNode
167
- ? { topics: [this._versionedTopicNode] }
168
- : null;
169
- }
170
-
171
- private _versionedTopicNode: VersionedNode | null = null;
172
-
173
119
  @api
174
120
  get contentType(): string {
175
121
  return this._contentType;
@@ -206,76 +152,6 @@ export default class RedocReference extends LightningElement {
206
152
  return refCount > 1;
207
153
  }
208
154
 
209
- private _versions: ReferenceVersion[] = [];
210
-
211
- get versions(): ReferenceVersion[] {
212
- return this._versions;
213
- }
214
-
215
- /**
216
- * Picker hrefs for the open page. Both setters call this because LWC can
217
- * assign referenceConfig and versionedTopicTree in either order. The page
218
- * URL is already set by then and does not change for this instance.
219
- */
220
- private refreshVersions(): void {
221
- const versions = this._referenceConfig?.versions ?? [];
222
- const node = this._versionedTopicNode;
223
- if (!node?.versions?.length || typeof window === "undefined") {
224
- this._versions = versions;
225
- return;
226
- }
227
-
228
- // Same helper as the markdown sidebar. The same array means this page
229
- // is outside the topic, so the backend switching URLs stay as authored.
230
- const rewritten = getVersionPickerOptions(node);
231
- if (!rewritten || rewritten === node.versions) {
232
- this._versions = versions;
233
- return;
234
- }
235
-
236
- this._versions = versions.map((version) => {
237
- const href = rewritten.find((option) => option.id === version.id)
238
- ?.link?.href;
239
- if (!href || href === version.link?.href) {
240
- return version;
241
- }
242
- return {
243
- ...version,
244
- link: { ...version.link, href }
245
- };
246
- });
247
- }
248
-
249
- /** The version flagged `selected`, else the first (the latest/GA version). */
250
- get selectedVersion(): ReferenceVersion | null {
251
- const versions = this.versions;
252
- return versions.find((v) => v.selected) ?? versions[0] ?? null;
253
- }
254
-
255
- /** True when the selected version is the latest/GA one (index 0). */
256
- get latestVersion(): boolean {
257
- return this.versions.length
258
- ? this.selectedVersion?.id === this.versions[0].id
259
- : false;
260
- }
261
-
262
- get hasVersionPicker(): boolean {
263
- return this.versions.length > 0;
264
- }
265
-
266
- /** "Newer version available" banner info when on a non-latest version, else null. */
267
- private get oldVersionInfo(): DocPhaseInfo | null {
268
- if (this.versions.length > 1 && !this.latestVersion) {
269
- return oldVersionDocInfo(this.versions[0].link.href);
270
- }
271
- return null;
272
- }
273
-
274
- /** A single version has nothing to choose, so it renders read-only. */
275
- get isVersionReadOnly(): boolean {
276
- return this.versions.length === 1;
277
- }
278
-
279
155
  // Reads stored back target
280
156
  private getBackTargetFromSession(): string | null {
281
157
  return sessionStorage.getItem(BACK_TARGET_STORAGE_KEY);
@@ -310,88 +186,13 @@ export default class RedocReference extends LightningElement {
310
186
  private onBackClick = (event: Event): void => {
311
187
  event.preventDefault();
312
188
 
313
- const target = this.getVersionedBackTarget() ?? this.headerHref;
189
+ const target = this.getTranslatedBackTarget() ?? this.headerHref;
314
190
 
315
191
  if (target) {
316
192
  window.location.assign(target);
317
193
  }
318
194
  };
319
195
 
320
- /**
321
- * When the back target is in this spec's topic, return it on the
322
- * selected version. With no back target, do the same for the header
323
- * link when that link is the versioned parent.
324
- */
325
- private getVersionedBackTarget(): string | null {
326
- const stored = this.getTranslatedBackTarget();
327
- const selectedVersion = this.selectedVersion;
328
- const target = stored ?? this.headerHref;
329
- if (!target || !selectedVersion) {
330
- return stored;
331
- }
332
-
333
- let targetUrl: URL;
334
- try {
335
- targetUrl = new URL(target, window.location.origin);
336
- } catch {
337
- return target;
338
- }
339
-
340
- // The spec picker links can use a different file name in each version
341
- // (`sample-api` and `new-sample-api`). That pair cannot move a sibling
342
- // page between versions. The parent topic's switching URLs share one
343
- // slug, so the back target is rewritten from those.
344
- const rewriteVersions = this.backTargetVersions();
345
- const rewriteVersion =
346
- rewriteVersions.find(
347
- (version) => version.id === selectedVersion.id
348
- ) ?? selectedVersion;
349
- const familyHrefs = this._versionedTopicNode
350
- ? collectSubtreeCanonicalHrefs(this._versionedTopicNode).map(
351
- (href) => toCanonicalHref(href, rewriteVersions)
352
- )
353
- : [];
354
-
355
- const canonicalTarget = toCanonicalHref(
356
- targetUrl.pathname,
357
- rewriteVersions
358
- );
359
- const inFamily = familyHrefs.some(
360
- (href) => normalizePath(href) === normalizePath(canonicalTarget)
361
- );
362
- if (!inFamily) {
363
- return target;
364
- }
365
-
366
- const versioned = applyVersionToHref(
367
- canonicalTarget,
368
- rewriteVersion,
369
- rewriteVersions
370
- );
371
- if (!versioned) {
372
- return target;
373
- }
374
- return `${versioned}${targetUrl.search}${targetUrl.hash}`;
375
- }
376
-
377
- /**
378
- * Version URLs used to move the back target. Prefer the parent topic's
379
- * switching URLs. Fall back to the spec picker when this spec is the
380
- * versioned topic itself.
381
- */
382
- private backTargetVersions(): ReferenceVersion[] {
383
- const familyVersions = this._versionedTopicNode?.versions;
384
- if (!familyVersions?.length) {
385
- return this.versions;
386
- }
387
- return familyVersions.map((version) => ({
388
- id: version.id,
389
- label: version.label,
390
- link: { href: version.link?.href ?? "" },
391
- selected: version.id === this.selectedVersion?.id
392
- }));
393
- }
394
-
395
196
  private getTranslatedBackTarget(): string | null {
396
197
  const stored = this.getBackTargetFromSession();
397
198
  if (stored) {
@@ -401,9 +202,7 @@ export default class RedocReference extends LightningElement {
401
202
  }
402
203
 
403
204
  const referrer = this.getSameOriginReferrerHref();
404
- return referrer &&
405
- !this.isLocaleHref(new URL(referrer).pathname) &&
406
- !this.isVersionHref(new URL(referrer).pathname)
205
+ return referrer && !this.isLocaleHref(new URL(referrer).pathname)
407
206
  ? referrer
408
207
  : null;
409
208
  }
@@ -417,9 +216,7 @@ export default class RedocReference extends LightningElement {
417
216
  const segments = url.pathname.split("/").filter(Boolean);
418
217
 
419
218
  // docs -> right after "docs"; references -> after the product segment.
420
- const localeIndex = this.isDocContentType
421
- ? DOCS_LOCALE_SEGMENT_INDEX
422
- : REFERENCES_LOCALE_SEGMENT_INDEX;
219
+ const localeIndex = this.isDocContentType ? 1 : 2;
423
220
 
424
221
  if (segments[0] === DOCS_PATH_SEGMENT) {
425
222
  // Drop the existing locale segment, if any
@@ -444,10 +241,7 @@ export default class RedocReference extends LightningElement {
444
241
  }
445
242
 
446
243
  const referrerUrl = new URL(referrerHref);
447
- if (
448
- this.isLocaleHref(referrerUrl.pathname) ||
449
- this.isVersionHref(referrerUrl.pathname)
450
- ) {
244
+ if (this.isLocaleHref(referrerUrl.pathname)) {
451
245
  return;
452
246
  }
453
247
 
@@ -488,19 +282,6 @@ export default class RedocReference extends LightningElement {
488
282
  });
489
283
  }
490
284
 
491
- /**
492
- * switching version on this same page.
493
- */
494
- private isVersionHref(pathname: string): boolean {
495
- return this.versions.some((version) => {
496
- const href = version?.link?.href;
497
- return (
498
- !!href &&
499
- new URL(href, window.location.origin).pathname === pathname
500
- );
501
- });
502
- }
503
-
504
285
  /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
505
286
  get effectiveFooterOrigin(): string {
506
287
  return (
@@ -516,13 +297,6 @@ export default class RedocReference extends LightningElement {
516
297
  // Track the back target, preserving it across locale switches
517
298
  this.trackBackTarget();
518
299
 
519
- // Remember the selected version for the sidebar. Changing version
520
- // reloads this page.
521
- const topicKey = this.getParentTopicVersionKey();
522
- if (topicKey && this.selectedVersion) {
523
- persistTopicVersion(topicKey, this.selectedVersion.id);
524
- }
525
-
526
300
  window.addEventListener("scroll", this.handleScrollAndResize);
527
301
  window.addEventListener("resize", this.handleScrollAndResize);
528
302
  }
@@ -580,14 +354,6 @@ export default class RedocReference extends LightningElement {
580
354
  return parseInt(value, 10) || 0;
581
355
  }
582
356
 
583
- /** Redoc's LNB background color, themeable via `--doc-c-redoc-sidebar-bg`. */
584
- private get sidebarBackgroundColor(): string {
585
- const value = getComputedStyle(this.template.host).getPropertyValue(
586
- "--doc-c-redoc-sidebar-bg"
587
- );
588
- return value.trim() || "white";
589
- }
590
-
591
357
  /*
592
358
  ** Since we could not use --dx-g-global-header-height as getPropertyValue returns a calc expression,
593
359
  ** we are using the respective CSS variables to calculate the height.
@@ -703,14 +469,7 @@ export default class RedocReference extends LightningElement {
703
469
  specUrl,
704
470
  {
705
471
  // Dynamic scroll offset to account for headers
706
- scrollYOffset: this.calculateScrollYOffset,
707
- // Redoc's own styled background outranks injected
708
- // CSS, so the LNB background must be set via theme.
709
- theme: {
710
- sidebar: {
711
- backgroundColor: this.sidebarBackgroundColor
712
- }
713
- }
472
+ scrollYOffset: this.calculateScrollYOffset
714
473
  },
715
474
  redocContainer,
716
475
  (error: any) => {
@@ -756,7 +515,10 @@ export default class RedocReference extends LightningElement {
756
515
  const apiContentDiv = await this.waitForApiContent(redocContainer);
757
516
  apiContentDiv.setAttribute("lwc:dom", "manual");
758
517
 
759
- this.insertStatusItems(apiContentDiv);
518
+ const docPhaseInfo = this.getDocPhaseInfo();
519
+ if (docPhaseInfo) {
520
+ this.insertDocPhase(apiContentDiv, docPhaseInfo);
521
+ }
760
522
 
761
523
  this.appendFooterItems(apiContentDiv);
762
524
 
@@ -765,22 +527,10 @@ export default class RedocReference extends LightningElement {
765
527
 
766
528
  // Wait for footer to be rendered before updating styles
767
529
  requestAnimationFrame(() => {
768
- try {
769
- this.updateRedocThirdColumnStyle(redocContainer);
770
-
771
- // Restore the view selected before a version switch only
772
- // after all layout mutations (footer, header) are
773
- // complete, so the scroll lands on the correct element.
774
- this.restoreSelectedView();
775
-
776
- // Fix initial hash scroll after doc phase insertion
777
- this.handleInitialHashScrollFix();
778
- } catch (error) {
779
- this.showErrorUI(
780
- "Failed to integrate custom components:",
781
- error
782
- );
783
- }
530
+ this.updateRedocThirdColumnStyle(redocContainer);
531
+
532
+ // Fix initial hash scroll after doc phase insertion
533
+ this.handleInitialHashScrollFix();
784
534
  });
785
535
  } catch (error) {
786
536
  this.showErrorUI("Failed to integrate custom components:", error);
@@ -810,71 +560,6 @@ export default class RedocReference extends LightningElement {
810
560
  }
811
561
  }
812
562
 
813
- /** Builds the version picker DOM by reusing `dx-version-picker`. */
814
- private buildVersionPickerDom(): HTMLElement {
815
- const wrapper = document.createElement("div");
816
- wrapper.className = "redoc-version-picker";
817
-
818
- const picker = createElement("dx-version-picker", {
819
- is: VersionPicker
820
- });
821
-
822
- Object.assign(picker, {
823
- versions: this.versions,
824
- selectedVersion: this.selectedVersion,
825
- latestVersion: this.latestVersion,
826
- readOnly: this.isVersionReadOnly
827
- });
828
- picker.addEventListener("change", this.onVersionChange);
829
- wrapper.appendChild(picker);
830
-
831
- return wrapper;
832
- }
833
-
834
- /**
835
- * Key the sidebar uses for this topic's selected version.
836
- * Missing `versionTopicSessionKey` returns null so nothing is written.
837
- */
838
- private getParentTopicVersionKey(): string | null {
839
- const versionTopicSessionKey =
840
- this._referenceConfig?.versionTopicSessionKey;
841
- if (!versionTopicSessionKey) {
842
- return null;
843
- }
844
- return (
845
- getTopicVersionKey(
846
- { name: versionTopicSessionKey },
847
- this.language ?? undefined
848
- ) || null
849
- );
850
- }
851
-
852
- /** Stashes the current view (URL hash) before the version link navigates. */
853
- private onVersionChange = (): void => {
854
- sessionStorage.setItem(
855
- SELECTED_VIEW_STORAGE_KEY,
856
- window.location.hash || ""
857
- );
858
- };
859
-
860
- /**
861
- * Re-applies the view stashed before a version switch, if its anchor exists
862
- * in the new spec; otherwise a no-op (lands on the spec root).
863
- */
864
- private restoreSelectedView(): void {
865
- const storedHash = sessionStorage.getItem(SELECTED_VIEW_STORAGE_KEY);
866
- sessionStorage.removeItem(SELECTED_VIEW_STORAGE_KEY);
867
-
868
- if (!storedHash || window.location.hash) {
869
- return;
870
- }
871
-
872
- const targetId = storedHash.replace(/^#/, "");
873
- if (targetId && document.getElementById(targetId)) {
874
- window.location.hash = storedHash;
875
- }
876
- }
877
-
878
563
  /**
879
564
  * Builds the locale picker DOM by reusing `dx-sidebar-footer-nav`
880
565
  */
@@ -896,17 +581,12 @@ export default class RedocReference extends LightningElement {
896
581
  }
897
582
 
898
583
  /**
899
- * Builds the doc header: a title group (back link + spec title) and, when
900
- * versions are available, the version picker as a sibling row. Layout/gaps
901
- * are styled by the developer-website's redoc CSS.
584
+ * Builds a fresh project-title/spec-title header DOM node.
902
585
  */
903
586
  private buildProjectHeaderDom(): HTMLElement {
904
587
  const wrapper = document.createElement("div");
905
588
  wrapper.className = "redoc-project-header";
906
589
 
907
- const main = document.createElement("div");
908
- main.className = "redoc-project-header-main";
909
-
910
590
  if (this.projectTitle) {
911
591
  const backLink = document.createElement("a");
912
592
  backLink.className = "redoc-project-back";
@@ -927,20 +607,14 @@ export default class RedocReference extends LightningElement {
927
607
 
928
608
  backLink.appendChild(icon);
929
609
  backLink.appendChild(label);
930
- main.appendChild(backLink);
610
+ wrapper.appendChild(backLink);
931
611
  }
932
612
 
933
613
  if (this.specTitle) {
934
614
  const specEl = document.createElement("h2");
935
615
  specEl.className = "redoc-spec-title dx-text-display-7";
936
616
  specEl.textContent = this.specTitle;
937
- main.appendChild(specEl);
938
- }
939
-
940
- wrapper.appendChild(main);
941
-
942
- if (this.hasVersionPicker) {
943
- wrapper.appendChild(this.buildVersionPickerDom());
617
+ wrapper.appendChild(specEl);
944
618
  }
945
619
 
946
620
  return wrapper;
@@ -965,40 +639,15 @@ export default class RedocReference extends LightningElement {
965
639
  return container.querySelector<HTMLElement>(".api-content")!;
966
640
  }
967
641
 
968
- // Inserts the doc phase and, on a non-latest version, a dismissible
969
- // "newer version" banner into a shared doc-phase-wrapper at container start
970
- private insertStatusItems(container: HTMLElement): void {
971
- const docPhaseInfo = this.getDocPhaseInfo();
972
- const oldVersionInfo = this.oldVersionInfo;
973
- if (!docPhaseInfo && !oldVersionInfo) {
974
- return;
975
- }
976
-
642
+ // Creates and inserts doc phase component at container start
643
+ private insertDocPhase(container: HTMLElement, docPhaseInfo: string): void {
977
644
  const wrapper = document.createElement("div");
978
645
  wrapper.className = "doc-phase-wrapper";
979
646
  container.insertBefore(wrapper, container.firstChild);
980
647
 
981
- if (docPhaseInfo) {
982
- const docPhaseElement = createElement("doc-phase", {
983
- is: DocPhase
984
- });
985
- Object.assign(docPhaseElement, { docPhaseInfo });
986
- wrapper.appendChild(docPhaseElement);
987
- }
988
-
989
- if (oldVersionInfo) {
990
- const versionBanner = createElement("doc-phase", { is: DocPhase });
991
- Object.assign(versionBanner, {
992
- docPhaseInfo: oldVersionInfo,
993
- dismissible: true,
994
- iconName: "warning"
995
- });
996
- versionBanner.addEventListener("dismissphase", () => {
997
- versionBanner.remove();
998
- this.updateSidebarPosition();
999
- });
1000
- wrapper.appendChild(versionBanner);
1001
- }
648
+ const docPhaseElement = createElement("doc-phase", { is: DocPhase });
649
+ Object.assign(docPhaseElement, { docPhaseInfo });
650
+ wrapper.appendChild(docPhaseElement);
1002
651
  }
1003
652
 
1004
653
  // Appends footer component to container
@@ -24,14 +24,6 @@
24
24
  lwc:if={docPhaseInfo}
25
25
  doc-phase-info={docPhaseInfo}
26
26
  ></doc-phase>
27
- <doc-phase
28
- slot="version-banner"
29
- lwc:if={showVersionBanner}
30
- doc-phase-info={oldVersionInfo}
31
- icon-name="warning"
32
- dismissible="true"
33
- ondismissphase={handleDismissVersionBanner}
34
- ></doc-phase>
35
27
  <slot></slot>
36
28
  </doc-content-layout>
37
29
  </template>
@@ -1,12 +1,6 @@
1
- import { LightningElement, api, track } from "lwc";
1
+ import { LightningElement, api } from "lwc";
2
2
  import { toJson } from "dxUtils/normalizers";
3
- import type { VersionedNode } from "dxUtils/topicVersion";
4
- import {
5
- findTopicVersionForCurrentPage,
6
- latestHrefForCurrentPage
7
- } from "dxUtils/topicVersion";
8
- import { oldVersionDocInfo } from "docUtils/utils";
9
- import type { DocPhaseInfo, OptionWithLink, TreeNode } from "typings/custom";
3
+ import type { OptionWithLink, TreeNode } from "typings/custom";
10
4
 
11
5
  /**
12
6
  * Per-topic type emitted by the docs content-type parser
@@ -16,48 +10,61 @@ import type { DocPhaseInfo, OptionWithLink, TreeNode } from "typings/custom";
16
10
  */
17
11
  const TOPIC_TYPE_SPEC = "spec";
18
12
 
13
+ /**
14
+ * Walks down the first-child chain and returns the first markdown content
15
+ * page found, descending through nested content-less parents. Returns
16
+ * undefined if the chain breaks on a spec or external link before reaching a
17
+ * content page.
18
+ */
19
+ function firstChildContentPage(node: TreeNode): TreeNode | undefined {
20
+ const firstChild = node.children?.[0];
21
+ if (!firstChild) {
22
+ return undefined;
23
+ }
24
+
25
+ const isSpec =
26
+ (firstChild as { topicType?: string }).topicType === TOPIC_TYPE_SPEC;
27
+ const isExternal = firstChild.link?.target === "_blank";
28
+ if (isSpec || isExternal) {
29
+ return undefined;
30
+ }
31
+
32
+ if (firstChild.link?.href) {
33
+ return firstChild;
34
+ }
35
+
36
+ return firstChildContentPage(firstChild);
37
+ }
38
+
19
39
  /**
20
40
  * Translates per-topic `topicType` into the generic `showForwardArrow` flag
21
- * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc).
22
- *
23
- * Content-less parents are flagged with redirectToChild and left without a
24
- * link. The tree selects the first markdown descendant. Copying that child's
25
- * href onto the parent makes the parent win selection.
41
+ * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc),
42
+ * and redirects content-less parent topics whose first child is a content page
26
43
  */
27
- function decorateTopicsWithForwardArrow(
28
- topics:
29
- | Array<TreeNode & { topicType?: string; versions?: unknown }>
30
- | undefined
44
+ function decorateTopics(
45
+ topics: Array<TreeNode & { topicType?: string }> | undefined
31
46
  ): TreeNode[] | undefined {
32
47
  return topics?.map((topic) => {
33
- const { topicType, versions, ...decorated } = topic;
48
+ const { topicType, ...decorated } = topic;
34
49
  if (topicType === TOPIC_TYPE_SPEC) {
35
50
  decorated.showForwardArrow = true;
36
- // Nested and standalone specs never get a sidebar picker; only the
37
- // parent MD topic (when versioned) shows one.
38
- } else if (Array.isArray(versions)) {
39
- decorated.versions = versions.map(
40
- (version: { children?: TreeNode[] }) =>
41
- version.children
42
- ? {
43
- ...version,
44
- children: decorateTopicsWithForwardArrow(
45
- version.children
46
- )
47
- }
48
- : version
49
- );
50
51
  }
51
52
  if (decorated.children) {
52
- decorated.children = decorateTopicsWithForwardArrow(
53
- decorated.children
54
- );
53
+ decorated.children = decorateTopics(decorated.children);
55
54
  }
56
55
 
57
- // Flag a parent with no page of its own. Leave its link empty so the
58
- // child's URL stays indexed to the child.
59
- if (!!decorated.children?.length && !decorated.link?.href) {
56
+ /** Redirect a parent that has no content of its own to its first child
57
+ * but only when that first child is itself a content page
58
+ */
59
+ const isContentlessParent =
60
+ !!decorated.children?.length && !decorated.link?.href;
61
+
62
+ if (isContentlessParent) {
60
63
  decorated.redirectToChild = true;
64
+ const firstChild = firstChildContentPage(topic);
65
+ if (firstChild?.link) {
66
+ decorated.link = { ...firstChild.link };
67
+ }
61
68
  }
62
69
 
63
70
  return decorated;
@@ -94,9 +101,6 @@ export default class UnifiedContentLayout extends LightningElement {
94
101
 
95
102
  private _docPhaseInfo: string | null = null;
96
103
  private _sidebarContent: unknown = null;
97
- private _oldVersionInfo: DocPhaseInfo | null = null;
98
-
99
- @track showVersionBanner = false;
100
104
 
101
105
  @api
102
106
  get docPhaseInfo(): string | null {
@@ -113,40 +117,7 @@ export default class UnifiedContentLayout extends LightningElement {
113
117
  }
114
118
 
115
119
  set sidebarContent(value: string) {
116
- const topics = decorateTopicsWithForwardArrow(toJson(value)?.topics);
117
- this._sidebarContent = topics;
118
- this.updateTopicVersionBanner(topics as VersionedNode[] | undefined);
119
- }
120
-
121
- get oldVersionInfo(): DocPhaseInfo | null {
122
- return this._oldVersionInfo;
123
- }
124
-
125
- handleDismissVersionBanner(): void {
126
- this.showVersionBanner = false;
127
- }
128
-
129
- /**
130
- * Same banner references use when the reader is on an older version.
131
- * Topic versions are not a separate page property: the sidebar tree
132
- * carries each version's switching URL, and the current pathname says
133
- * which one is open.
134
- */
135
- private updateTopicVersionBanner(
136
- topics: VersionedNode[] | undefined
137
- ): void {
138
- const match = findTopicVersionForCurrentPage(topics);
139
- const latest = match?.node.versions?.[0];
140
- const latestHref = latestHrefForCurrentPage(match?.node.versions);
141
-
142
- if (match && latest && match.version.id !== latest.id && latestHref) {
143
- this._oldVersionInfo = oldVersionDocInfo(latestHref);
144
- this.showVersionBanner = true;
145
- return;
146
- }
147
-
148
- this._oldVersionInfo = null;
149
- this.showVersionBanner = false;
120
+ this._sidebarContent = decorateTopics(toJson(value)?.topics);
150
121
  }
151
122
 
152
123
  private get enableFooter(): boolean {
@@ -0,0 +1,64 @@
1
+ @import "dxHelpers/reset";
2
+
3
+ /* NOTE: doc-version-picker-width width variable is used by both dx-button and dx-dropdown to maintain a consistent width. */
4
+ :host {
5
+ --dx-c-dropdown-option-font-weight: normal;
6
+ --dx-c-dropdown-option-label-color: var(--dx-g-gray-10);
7
+ --popover-container-open-transform: translateY(4px);
8
+ }
9
+
10
+ .version-picker-container {
11
+ padding: 8px var(--dx-g-spacing-lg) 8px
12
+ var(--dx-g-global-header-padding-horizontal);
13
+ border-top: 1px solid var(--dx-g-gray-90);
14
+ border-bottom: 1px solid var(--dx-g-gray-90);
15
+ }
16
+
17
+ .version-picker-button {
18
+ display: flex;
19
+ width: var(--doc-version-picker-width, 296px);
20
+ }
21
+
22
+ .version-picker-button:hover,
23
+ .version-picker-button:active,
24
+ .version-picker-button:focus {
25
+ --dx-c-button-secondary-color-hover: var(--dx-g-cloud-blue-vibrant-95);
26
+ --dx-c-button-primary-color: var(--dx-g-blue-vibrant-40);
27
+ }
28
+
29
+ /**
30
+ * NOTE: This CSS ensures the span inside the button stays within the parent's width, avoiding overflow.
31
+ * Not keeping this in common component to ensure that existing functionality works as it is.
32
+ */
33
+ dx-button::part(content) {
34
+ width: inherit;
35
+ overflow: hidden;
36
+ }
37
+
38
+ .selected-version {
39
+ display: flex;
40
+ flex-direction: row;
41
+ align-items: center;
42
+ }
43
+
44
+ .selected-version-label {
45
+ flex: 1;
46
+ overflow: hidden;
47
+ text-align: left;
48
+ text-overflow: ellipsis;
49
+ white-space: nowrap;
50
+ }
51
+
52
+ dx-type-badge.latest-badge {
53
+ --dx-c-type-badge-color: var(--dx-g-green-vibrant-40);
54
+ --dx-c-type-badge-background: var(--dx-g-green-vibrant-95);
55
+
56
+ margin-left: var(--dx-g-spacing-sm);
57
+ }
58
+
59
+ dx-type-badge.not-latest-badge {
60
+ --dx-c-type-badge-color: var(--dx-g-red-vibrant-40);
61
+ --dx-c-type-badge-background: var(--dx-g-red-vibrant-95);
62
+
63
+ margin-left: var(--dx-g-spacing-sm);
64
+ }
@@ -0,0 +1,40 @@
1
+ <template>
2
+ <div lwc:if={showVersionPicker} class="version-picker-container">
3
+ <dx-dropdown
4
+ options={versions}
5
+ analytics-event="custEv_docVersionSelect"
6
+ analytics-payload={analyticsPayload}
7
+ value={selectedVersion.id}
8
+ width="var(--doc-version-picker-width)"
9
+ onchange={onVersionChange}
10
+ >
11
+ <dx-button
12
+ class="version-picker-button"
13
+ variant="tertiary"
14
+ size="small"
15
+ icon-symbol="chevrondown"
16
+ icon-size="medium"
17
+ >
18
+ <div class="selected-version">
19
+ <p class="selected-version-label">
20
+ {selectedVersion.label}
21
+ </p>
22
+ <template lwc:if={showLatestTag}>
23
+ <dx-type-badge
24
+ class="latest-badge"
25
+ lwc:if={latestVersion}
26
+ value="Latest"
27
+ size="small"
28
+ ></dx-type-badge>
29
+ <dx-type-badge
30
+ class="not-latest-badge"
31
+ lwc:else
32
+ value="Not Latest"
33
+ size="small"
34
+ ></dx-type-badge>
35
+ </template>
36
+ </div>
37
+ </dx-button>
38
+ </dx-dropdown>
39
+ </div>
40
+ </template>
@@ -0,0 +1,65 @@
1
+ import { LightningElement, api, track } from "lwc";
2
+
3
+ import { AnalyticsPayload, OptionWithNested } from "typings/custom";
4
+
5
+ import { toJson, normalizeBoolean } from "dxUtils/normalizers";
6
+
7
+ export default class VersionPicker extends LightningElement {
8
+ @api analyticsEvent?: string;
9
+ @api analyticsPayload?: AnalyticsPayload;
10
+
11
+ @track private _versions!: OptionWithNested[];
12
+ private _selectedVersion?: OptionWithNested;
13
+ private _latestVersion: boolean = false;
14
+ private _hideBadge: boolean = false;
15
+
16
+ @api
17
+ get versions() {
18
+ return this._versions;
19
+ }
20
+
21
+ set versions(value: OptionWithNested[]) {
22
+ this._versions = toJson(value);
23
+ }
24
+
25
+ @api
26
+ get selectedVersion(): OptionWithNested | undefined {
27
+ return this._selectedVersion || this.versions[0];
28
+ }
29
+
30
+ set selectedVersion(value: OptionWithNested) {
31
+ if (value) {
32
+ this._selectedVersion = toJson(value);
33
+ }
34
+ }
35
+
36
+ @api
37
+ get latestVersion() {
38
+ return this._latestVersion;
39
+ }
40
+
41
+ set latestVersion(value) {
42
+ this._latestVersion = normalizeBoolean(value);
43
+ }
44
+
45
+ @api
46
+ get hideBadge() {
47
+ return this._hideBadge;
48
+ }
49
+
50
+ set hideBadge(value) {
51
+ this._hideBadge = normalizeBoolean(value);
52
+ }
53
+
54
+ private get showVersionPicker() {
55
+ return this._versions && this._versions.length !== 0;
56
+ }
57
+
58
+ private get showLatestTag(): boolean {
59
+ return !this.hideBadge;
60
+ }
61
+
62
+ private onVersionChange(e: CustomEvent) {
63
+ this.dispatchEvent(new CustomEvent("change", { detail: e.detail }));
64
+ }
65
+ }
@@ -25,7 +25,7 @@
25
25
  ondismissphase={handleDismissVersionBanner}
26
26
  ></doc-phase>
27
27
  <div lwc:if={showVersionPicker} slot="sidebar-header">
28
- <dx-version-picker
28
+ <doc-version-picker
29
29
  data-type="version"
30
30
  analytics-event="custEv_linkClick"
31
31
  analytics-payload={ANALYTICS_PAYLOAD}
@@ -33,7 +33,7 @@
33
33
  selected-version={version}
34
34
  latest-version={latestVersion}
35
35
  hide-badge={previewVersion}
36
- ></dx-version-picker>
36
+ ></doc-version-picker>
37
37
  </div>
38
38
  <div class="breadcrumb-row" lwc:if={showBreadcrumbs}>
39
39
  <doc-breadcrumbs
@@ -1,30 +1,10 @@
1
1
  import { CoveoAnalyticsClient } from "coveo.analytics/dist/browser.mjs"; // This fix is required for Node 20 upgrade, so that Coveo analytics is loaded properly by LWR.
2
2
 
3
- // Resolve against the current origin (version links are usually relative) and
4
- // keep only http/https. Blocks executable schemes like javascript:/data: that
5
- // would run when the innerHTML-rendered link is clicked.
6
- // The link is already percent-encoded: location.pathname and AMF queries such
7
- // as type%3A. encodeURI would encode "%" again (%20 -> %2520) and the View
8
- // Latest href would 404. Escape only the quote that would close the attribute.
9
- const toSafeHref = (link: string): string => {
10
- try {
11
- const { protocol } = new URL(link, window.location.origin);
12
- if (protocol === "http:" || protocol === "https:") {
13
- return link.replace(/"/g, "%22");
14
- }
15
- } catch {
16
- // Fall through to the rejection below.
17
- }
18
- console.warn(`Blocked unsafe version link: ${link}`);
19
- return "#";
20
- };
21
-
22
3
  export const oldVersionDocInfo = (latestVersionLink: string) => {
23
- const safeLink = toSafeHref(latestVersionLink);
24
4
  return {
25
5
  title: "Newer Version Available",
26
- body: `This content describes an older version of this product.
27
- <a style="font-weight: bold;" href="${safeLink}">View Latest</a>`
6
+ body: `This content describes an older version of this product.
7
+ <a style="font-weight: bold;" href="${latestVersionLink}">View Latest</a>`
28
8
  };
29
9
  };
30
10