@salesforcedevs/docs-components 1.34.5-tlv-alpha → 1.34.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,12 @@
1
+ Copyright (c) 2020, Salesforce.com, Inc.
2
+ All rights reserved.
3
+
4
+ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
5
+
6
+ * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
7
+
8
+ * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
9
+
10
+ * Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
11
+
12
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
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,29 +1,29 @@
1
1
  {
2
- "name": "@salesforcedevs/docs-components",
3
- "version": "1.34.5-tlv-alpha",
4
- "description": "Docs Lightning web components for DSC",
5
- "license": "MIT",
6
- "main": "index.js",
7
- "engines": {
8
- "node": "22.x"
9
- },
10
- "publishConfig": {
11
- "access": "public"
12
- },
13
- "dependencies": {
14
- "@api-components/amf-helper-mixin": "4.5.29",
15
- "classnames": "2.5.1",
16
- "dompurify": "3.2.4",
17
- "kagekiri": "1.4.2",
18
- "lodash.orderby": "4.6.0",
19
- "lodash.uniqby": "4.7.0",
20
- "query-string": "7.1.3",
21
- "sentence-case": "3.0.4"
22
- },
23
- "devDependencies": {
24
- "@types/classnames": "2.3.1",
25
- "@types/lodash.orderby": "4.6.9",
26
- "@types/lodash.uniqby": "4.7.9"
27
- },
28
- "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
29
- }
2
+ "name": "@salesforcedevs/docs-components",
3
+ "version": "1.34.6",
4
+ "description": "Docs Lightning web components for DSC",
5
+ "license": "MIT",
6
+ "main": "index.js",
7
+ "engines": {
8
+ "node": "22.x"
9
+ },
10
+ "publishConfig": {
11
+ "access": "public"
12
+ },
13
+ "dependencies": {
14
+ "@api-components/amf-helper-mixin": "4.5.29",
15
+ "classnames": "2.5.1",
16
+ "dompurify": "3.2.4",
17
+ "kagekiri": "1.4.2",
18
+ "lodash.orderby": "4.6.0",
19
+ "lodash.uniqby": "4.7.0",
20
+ "query-string": "7.1.3",
21
+ "sentence-case": "3.0.4"
22
+ },
23
+ "devDependencies": {
24
+ "@types/classnames": "2.3.1",
25
+ "@types/lodash.orderby": "4.6.9",
26
+ "@types/lodash.uniqby": "4.7.9"
27
+ },
28
+ "gitHead": "fbb4c02118f970fa5be88e91ea5a5023da9b8576"
29
+ }
@@ -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,25 +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
- persistTopicVersion,
21
- REFERENCES_LOCALE_SEGMENT_INDEX,
22
- toCanonicalHref
23
- } from "dxUtils/topicVersion";
24
- import type { VersionedNode } from "dxUtils/topicVersion";
25
- import type { DocPhaseInfo, OptionWithLink } from "typings/custom";
11
+ import type { OptionWithLink } from "typings/custom";
26
12
 
27
13
  declare global {
28
14
  interface Window {
@@ -47,20 +33,8 @@ type ReferenceItem = {
47
33
  topic?: ReferenceTopic;
48
34
  };
49
35
 
50
- /** A selectable spec version. Mirrors `ReferenceVersion` in `doc/amfReference`. */
51
- type ReferenceVersion = {
52
- id: string;
53
- label: string;
54
- deprecated?: boolean;
55
- selected?: boolean;
56
- link: { href: string };
57
- };
58
-
59
36
  type ReferenceConfig = {
60
37
  refList: ReferenceItem[];
61
- versions?: ReferenceVersion[];
62
- /** Sidebar topic name. Sidebar stores the selected version under this key. */
63
- versionTopicKey?: string;
64
38
  };
65
39
 
66
40
  const SCROLL_THROTTLE_DELAY = 50;
@@ -68,7 +42,7 @@ const ELEMENT_TIMEOUT = 10000;
68
42
  const ELEMENT_CHECK_INTERVAL = 100;
69
43
  const DEFAULT_PROJECT_TITLE = "All Reference";
70
44
  const BACK_TARGET_STORAGE_KEY = "redoc-back-target";
71
- const SELECTED_VIEW_STORAGE_KEY = "redoc-selected-view";
45
+ const DOCS_PATH_SEGMENT = "docs";
72
46
  const DEFAULT_LOCALE = "en-us";
73
47
 
74
48
  export default class RedocReference extends LightningElement {
@@ -142,29 +116,6 @@ export default class RedocReference extends LightningElement {
142
116
  */
143
117
  @api headerHref: string | null = null;
144
118
 
145
- /**
146
- * Versioned topic that owns this spec, including its children.
147
- * Href matches this page, so an older version still has its version
148
- * in the path.
149
- */
150
- @api
151
- set parentTopicFamily(value: string | { topics?: VersionedNode[] } | null) {
152
- try {
153
- const parsed = toJson(value) as { topics?: VersionedNode[] } | null;
154
- this._parentTopicFamilyNode = parsed?.topics?.[0] ?? null;
155
- } catch (error) {
156
- this._parentTopicFamilyNode = null;
157
- }
158
- }
159
-
160
- get parentTopicFamily(): { topics?: VersionedNode[] } | null {
161
- return this._parentTopicFamilyNode
162
- ? { topics: [this._parentTopicFamilyNode] }
163
- : null;
164
- }
165
-
166
- private _parentTopicFamilyNode: VersionedNode | null = null;
167
-
168
119
  @api
169
120
  get contentType(): string {
170
121
  return this._contentType;
@@ -201,40 +152,6 @@ export default class RedocReference extends LightningElement {
201
152
  return refCount > 1;
202
153
  }
203
154
 
204
- get versions(): ReferenceVersion[] {
205
- return this._referenceConfig?.versions ?? [];
206
- }
207
-
208
- /** The version flagged `selected`, else the first (the latest/GA version). */
209
- get selectedVersion(): ReferenceVersion | null {
210
- const versions = this.versions;
211
- return versions.find((v) => v.selected) ?? versions[0] ?? null;
212
- }
213
-
214
- /** True when the selected version is the latest/GA one (index 0). */
215
- get latestVersion(): boolean {
216
- return this.versions.length
217
- ? this.selectedVersion?.id === this.versions[0].id
218
- : false;
219
- }
220
-
221
- get hasVersionPicker(): boolean {
222
- return this.versions.length > 0;
223
- }
224
-
225
- /** "Newer version available" banner info when on a non-latest version, else null. */
226
- private get oldVersionInfo(): DocPhaseInfo | null {
227
- if (this.versions.length > 1 && !this.latestVersion) {
228
- return oldVersionDocInfo(this.versions[0].link.href);
229
- }
230
- return null;
231
- }
232
-
233
- /** A single version has nothing to choose, so it renders read-only. */
234
- get isVersionReadOnly(): boolean {
235
- return this.versions.length === 1;
236
- }
237
-
238
155
  // Reads stored back target
239
156
  private getBackTargetFromSession(): string | null {
240
157
  return sessionStorage.getItem(BACK_TARGET_STORAGE_KEY);
@@ -269,64 +186,13 @@ export default class RedocReference extends LightningElement {
269
186
  private onBackClick = (event: Event): void => {
270
187
  event.preventDefault();
271
188
 
272
- const target = this.getVersionedBackTarget() ?? this.headerHref;
189
+ const target = this.getTranslatedBackTarget() ?? this.headerHref;
273
190
 
274
191
  if (target) {
275
192
  window.location.assign(target);
276
193
  }
277
194
  };
278
195
 
279
- /**
280
- * When the back target is in this spec's topic, return it on the
281
- * selected version. With no back target, do the same for the header
282
- * link when that link is the versioned parent.
283
- */
284
- private getVersionedBackTarget(): string | null {
285
- const stored = this.getTranslatedBackTarget();
286
- const selectedVersion = this.selectedVersion;
287
- const target = stored ?? this.headerHref;
288
- if (!target || !selectedVersion) {
289
- return stored;
290
- }
291
-
292
- let targetUrl: URL;
293
- try {
294
- targetUrl = new URL(target, window.location.origin);
295
- } catch {
296
- return target;
297
- }
298
-
299
- // Family hrefs match this page's version. Compare them without
300
- // the version segment. Rewrite only the pathname so the target's
301
- // query and hash survive.
302
- const familyHrefs = this._parentTopicFamilyNode
303
- ? collectSubtreeCanonicalHrefs(this._parentTopicFamilyNode).map(
304
- (href) => toCanonicalHref(href, this.versions)
305
- )
306
- : [];
307
-
308
- const canonicalTarget = toCanonicalHref(
309
- targetUrl.pathname,
310
- this.versions
311
- );
312
- const inFamily = familyHrefs.some(
313
- (href) => normalizePath(href) === normalizePath(canonicalTarget)
314
- );
315
- if (!inFamily) {
316
- return target;
317
- }
318
-
319
- const versioned = applyVersionToHref(
320
- canonicalTarget,
321
- selectedVersion,
322
- this.versions
323
- );
324
- if (!versioned) {
325
- return target;
326
- }
327
- return `${versioned}${targetUrl.search}${targetUrl.hash}`;
328
- }
329
-
330
196
  private getTranslatedBackTarget(): string | null {
331
197
  const stored = this.getBackTargetFromSession();
332
198
  if (stored) {
@@ -336,9 +202,7 @@ export default class RedocReference extends LightningElement {
336
202
  }
337
203
 
338
204
  const referrer = this.getSameOriginReferrerHref();
339
- return referrer &&
340
- !this.isLocaleHref(new URL(referrer).pathname) &&
341
- !this.isVersionHref(new URL(referrer).pathname)
205
+ return referrer && !this.isLocaleHref(new URL(referrer).pathname)
342
206
  ? referrer
343
207
  : null;
344
208
  }
@@ -352,9 +216,7 @@ export default class RedocReference extends LightningElement {
352
216
  const segments = url.pathname.split("/").filter(Boolean);
353
217
 
354
218
  // docs -> right after "docs"; references -> after the product segment.
355
- const localeIndex = this.isDocContentType
356
- ? DOCS_LOCALE_SEGMENT_INDEX
357
- : REFERENCES_LOCALE_SEGMENT_INDEX;
219
+ const localeIndex = this.isDocContentType ? 1 : 2;
358
220
 
359
221
  if (segments[0] === DOCS_PATH_SEGMENT) {
360
222
  // Drop the existing locale segment, if any
@@ -379,10 +241,7 @@ export default class RedocReference extends LightningElement {
379
241
  }
380
242
 
381
243
  const referrerUrl = new URL(referrerHref);
382
- if (
383
- this.isLocaleHref(referrerUrl.pathname) ||
384
- this.isVersionHref(referrerUrl.pathname)
385
- ) {
244
+ if (this.isLocaleHref(referrerUrl.pathname)) {
386
245
  return;
387
246
  }
388
247
 
@@ -423,19 +282,6 @@ export default class RedocReference extends LightningElement {
423
282
  });
424
283
  }
425
284
 
426
- /**
427
- * switching version on this same page.
428
- */
429
- private isVersionHref(pathname: string): boolean {
430
- return this.versions.some((version) => {
431
- const href = version?.link?.href;
432
- return (
433
- !!href &&
434
- new URL(href, window.location.origin).pathname === pathname
435
- );
436
- });
437
- }
438
-
439
285
  /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
440
286
  get effectiveFooterOrigin(): string {
441
287
  return (
@@ -451,13 +297,6 @@ export default class RedocReference extends LightningElement {
451
297
  // Track the back target, preserving it across locale switches
452
298
  this.trackBackTarget();
453
299
 
454
- // Remember the selected version for the sidebar. Changing version
455
- // reloads this page.
456
- const topicKey = this.getParentTopicVersionKey();
457
- if (topicKey && this.selectedVersion) {
458
- persistTopicVersion(topicKey, this.selectedVersion.id);
459
- }
460
-
461
300
  window.addEventListener("scroll", this.handleScrollAndResize);
462
301
  window.addEventListener("resize", this.handleScrollAndResize);
463
302
  }
@@ -515,14 +354,6 @@ export default class RedocReference extends LightningElement {
515
354
  return parseInt(value, 10) || 0;
516
355
  }
517
356
 
518
- /** Redoc's LNB background color, themeable via `--doc-c-redoc-sidebar-bg`. */
519
- private get sidebarBackgroundColor(): string {
520
- const value = getComputedStyle(this.template.host).getPropertyValue(
521
- "--doc-c-redoc-sidebar-bg"
522
- );
523
- return value.trim() || "white";
524
- }
525
-
526
357
  /*
527
358
  ** Since we could not use --dx-g-global-header-height as getPropertyValue returns a calc expression,
528
359
  ** we are using the respective CSS variables to calculate the height.
@@ -638,14 +469,7 @@ export default class RedocReference extends LightningElement {
638
469
  specUrl,
639
470
  {
640
471
  // Dynamic scroll offset to account for headers
641
- scrollYOffset: this.calculateScrollYOffset,
642
- // Redoc's own styled background outranks injected
643
- // CSS, so the LNB background must be set via theme.
644
- theme: {
645
- sidebar: {
646
- backgroundColor: this.sidebarBackgroundColor
647
- }
648
- }
472
+ scrollYOffset: this.calculateScrollYOffset
649
473
  },
650
474
  redocContainer,
651
475
  (error: any) => {
@@ -691,7 +515,10 @@ export default class RedocReference extends LightningElement {
691
515
  const apiContentDiv = await this.waitForApiContent(redocContainer);
692
516
  apiContentDiv.setAttribute("lwc:dom", "manual");
693
517
 
694
- this.insertStatusItems(apiContentDiv);
518
+ const docPhaseInfo = this.getDocPhaseInfo();
519
+ if (docPhaseInfo) {
520
+ this.insertDocPhase(apiContentDiv, docPhaseInfo);
521
+ }
695
522
 
696
523
  this.appendFooterItems(apiContentDiv);
697
524
 
@@ -700,22 +527,10 @@ export default class RedocReference extends LightningElement {
700
527
 
701
528
  // Wait for footer to be rendered before updating styles
702
529
  requestAnimationFrame(() => {
703
- try {
704
- this.updateRedocThirdColumnStyle(redocContainer);
705
-
706
- // Restore the view selected before a version switch only
707
- // after all layout mutations (footer, header) are
708
- // complete, so the scroll lands on the correct element.
709
- this.restoreSelectedView();
710
-
711
- // Fix initial hash scroll after doc phase insertion
712
- this.handleInitialHashScrollFix();
713
- } catch (error) {
714
- this.showErrorUI(
715
- "Failed to integrate custom components:",
716
- error
717
- );
718
- }
530
+ this.updateRedocThirdColumnStyle(redocContainer);
531
+
532
+ // Fix initial hash scroll after doc phase insertion
533
+ this.handleInitialHashScrollFix();
719
534
  });
720
535
  } catch (error) {
721
536
  this.showErrorUI("Failed to integrate custom components:", error);
@@ -745,70 +560,6 @@ export default class RedocReference extends LightningElement {
745
560
  }
746
561
  }
747
562
 
748
- /** Builds the version picker DOM by reusing `dx-version-picker`. */
749
- private buildVersionPickerDom(): HTMLElement {
750
- const wrapper = document.createElement("div");
751
- wrapper.className = "redoc-version-picker";
752
-
753
- const picker = createElement("dx-version-picker", {
754
- is: VersionPicker
755
- });
756
-
757
- Object.assign(picker, {
758
- versions: this.versions,
759
- selectedVersion: this.selectedVersion,
760
- latestVersion: this.latestVersion,
761
- readOnly: this.isVersionReadOnly
762
- });
763
- picker.addEventListener("change", this.onVersionChange);
764
- wrapper.appendChild(picker);
765
-
766
- return wrapper;
767
- }
768
-
769
- /**
770
- * Key the sidebar uses for this topic's selected version.
771
- * Missing `versionTopicKey` returns null so nothing is written.
772
- */
773
- private getParentTopicVersionKey(): string | null {
774
- const versionTopicKey = this._referenceConfig?.versionTopicKey;
775
- if (!versionTopicKey) {
776
- return null;
777
- }
778
- return (
779
- getTopicVersionKey(
780
- { name: versionTopicKey },
781
- this.language ?? undefined
782
- ) || null
783
- );
784
- }
785
-
786
- /** Stashes the current view (URL hash) before the version link navigates. */
787
- private onVersionChange = (): void => {
788
- sessionStorage.setItem(
789
- SELECTED_VIEW_STORAGE_KEY,
790
- window.location.hash || ""
791
- );
792
- };
793
-
794
- /**
795
- * Re-applies the view stashed before a version switch, if its anchor exists
796
- * in the new spec; otherwise a no-op (lands on the spec root).
797
- */
798
- private restoreSelectedView(): void {
799
- const storedHash = sessionStorage.getItem(SELECTED_VIEW_STORAGE_KEY);
800
- sessionStorage.removeItem(SELECTED_VIEW_STORAGE_KEY);
801
-
802
- if (!storedHash || window.location.hash) {
803
- return;
804
- }
805
-
806
- const targetId = storedHash.replace(/^#/, "");
807
- if (targetId && document.getElementById(targetId)) {
808
- window.location.hash = storedHash;
809
- }
810
- }
811
-
812
563
  /**
813
564
  * Builds the locale picker DOM by reusing `dx-sidebar-footer-nav`
814
565
  */
@@ -830,17 +581,12 @@ export default class RedocReference extends LightningElement {
830
581
  }
831
582
 
832
583
  /**
833
- * Builds the doc header: a title group (back link + spec title) and, when
834
- * versions are available, the version picker as a sibling row. Layout/gaps
835
- * are styled by the developer-website's redoc CSS.
584
+ * Builds a fresh project-title/spec-title header DOM node.
836
585
  */
837
586
  private buildProjectHeaderDom(): HTMLElement {
838
587
  const wrapper = document.createElement("div");
839
588
  wrapper.className = "redoc-project-header";
840
589
 
841
- const main = document.createElement("div");
842
- main.className = "redoc-project-header-main";
843
-
844
590
  if (this.projectTitle) {
845
591
  const backLink = document.createElement("a");
846
592
  backLink.className = "redoc-project-back";
@@ -861,20 +607,14 @@ export default class RedocReference extends LightningElement {
861
607
 
862
608
  backLink.appendChild(icon);
863
609
  backLink.appendChild(label);
864
- main.appendChild(backLink);
610
+ wrapper.appendChild(backLink);
865
611
  }
866
612
 
867
613
  if (this.specTitle) {
868
614
  const specEl = document.createElement("h2");
869
615
  specEl.className = "redoc-spec-title dx-text-display-7";
870
616
  specEl.textContent = this.specTitle;
871
- main.appendChild(specEl);
872
- }
873
-
874
- wrapper.appendChild(main);
875
-
876
- if (this.hasVersionPicker) {
877
- wrapper.appendChild(this.buildVersionPickerDom());
617
+ wrapper.appendChild(specEl);
878
618
  }
879
619
 
880
620
  return wrapper;
@@ -899,40 +639,15 @@ export default class RedocReference extends LightningElement {
899
639
  return container.querySelector<HTMLElement>(".api-content")!;
900
640
  }
901
641
 
902
- // Inserts the doc phase and, on a non-latest version, a dismissible
903
- // "newer version" banner into a shared doc-phase-wrapper at container start
904
- private insertStatusItems(container: HTMLElement): void {
905
- const docPhaseInfo = this.getDocPhaseInfo();
906
- const oldVersionInfo = this.oldVersionInfo;
907
- if (!docPhaseInfo && !oldVersionInfo) {
908
- return;
909
- }
910
-
642
+ // Creates and inserts doc phase component at container start
643
+ private insertDocPhase(container: HTMLElement, docPhaseInfo: string): void {
911
644
  const wrapper = document.createElement("div");
912
645
  wrapper.className = "doc-phase-wrapper";
913
646
  container.insertBefore(wrapper, container.firstChild);
914
647
 
915
- if (docPhaseInfo) {
916
- const docPhaseElement = createElement("doc-phase", {
917
- is: DocPhase
918
- });
919
- Object.assign(docPhaseElement, { docPhaseInfo });
920
- wrapper.appendChild(docPhaseElement);
921
- }
922
-
923
- if (oldVersionInfo) {
924
- const versionBanner = createElement("doc-phase", { is: DocPhase });
925
- Object.assign(versionBanner, {
926
- docPhaseInfo: oldVersionInfo,
927
- dismissible: true,
928
- iconName: "warning"
929
- });
930
- versionBanner.addEventListener("dismissphase", () => {
931
- versionBanner.remove();
932
- this.updateSidebarPosition();
933
- });
934
- wrapper.appendChild(versionBanner);
935
- }
648
+ const docPhaseElement = createElement("doc-phase", { is: DocPhase });
649
+ Object.assign(docPhaseElement, { docPhaseInfo });
650
+ wrapper.appendChild(docPhaseElement);
936
651
  }
937
652
 
938
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,38 +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 (versions) {
39
- decorated.versions = versions;
40
51
  }
41
52
  if (decorated.children) {
42
- decorated.children = decorateTopicsWithForwardArrow(
43
- decorated.children
44
- );
53
+ decorated.children = decorateTopics(decorated.children);
45
54
  }
46
55
 
47
- // Flag a parent with no page of its own. Leave its link empty so the
48
- // child's URL stays indexed to the child.
49
- 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) {
50
63
  decorated.redirectToChild = true;
64
+ const firstChild = firstChildContentPage(topic);
65
+ if (firstChild?.link) {
66
+ decorated.link = { ...firstChild.link };
67
+ }
51
68
  }
52
69
 
53
70
  return decorated;
@@ -84,9 +101,6 @@ export default class UnifiedContentLayout extends LightningElement {
84
101
 
85
102
  private _docPhaseInfo: string | null = null;
86
103
  private _sidebarContent: unknown = null;
87
- private _oldVersionInfo: DocPhaseInfo | null = null;
88
-
89
- @track showVersionBanner = false;
90
104
 
91
105
  @api
92
106
  get docPhaseInfo(): string | null {
@@ -103,40 +117,7 @@ export default class UnifiedContentLayout extends LightningElement {
103
117
  }
104
118
 
105
119
  set sidebarContent(value: string) {
106
- const topics = decorateTopicsWithForwardArrow(toJson(value)?.topics);
107
- this._sidebarContent = topics;
108
- this.updateTopicVersionBanner(topics as VersionedNode[] | undefined);
109
- }
110
-
111
- get oldVersionInfo(): DocPhaseInfo | null {
112
- return this._oldVersionInfo;
113
- }
114
-
115
- handleDismissVersionBanner(): void {
116
- this.showVersionBanner = false;
117
- }
118
-
119
- /**
120
- * Same banner references use when the reader is on an older version.
121
- * Topic versions are not a separate page property: the sidebar tree
122
- * carries each version's switching URL, and the current pathname says
123
- * which one is open.
124
- */
125
- private updateTopicVersionBanner(
126
- topics: VersionedNode[] | undefined
127
- ): void {
128
- const match = findTopicVersionForCurrentPage(topics);
129
- const latest = match?.node.versions?.[0];
130
- const latestHref = latestHrefForCurrentPage(match?.node.versions);
131
-
132
- if (match && latest && match.version.id !== latest.id && latestHref) {
133
- this._oldVersionInfo = oldVersionDocInfo(latestHref);
134
- this.showVersionBanner = true;
135
- return;
136
- }
137
-
138
- this._oldVersionInfo = null;
139
- this.showVersionBanner = false;
120
+ this._sidebarContent = decorateTopics(toJson(value)?.topics);
140
121
  }
141
122
 
142
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
+ }
@@ -24,7 +24,7 @@
24
24
  ondismissphase={handleDismissVersionBanner}
25
25
  ></doc-phase>
26
26
  <div lwc:if={showVersionPicker} slot="sidebar-header">
27
- <dx-version-picker
27
+ <doc-version-picker
28
28
  data-type="version"
29
29
  analytics-event="custEv_linkClick"
30
30
  analytics-payload={ANALYTICS_PAYLOAD}
@@ -32,7 +32,7 @@
32
32
  selected-version={version}
33
33
  latest-version={latestVersion}
34
34
  hide-badge={previewVersion}
35
- ></dx-version-picker>
35
+ ></doc-version-picker>
36
36
  </div>
37
37
  <div class="breadcrumb-row" lwc:if={showBreadcrumbs}>
38
38
  <doc-breadcrumbs
@@ -130,9 +130,16 @@ export default class DocXmlContent extends LightningElementWithState<{
130
130
  private get oldVersionInfo(): DocPhaseInfo | null {
131
131
  let info = null;
132
132
  if (!this.disableVersion) {
133
- const currentGAVersion = this.versionOptions.find(
134
- (version) => !version.url.includes(version.id)
135
- );
133
+ /**
134
+ * The GA version of en-us content has no version id in its url.
135
+ * Localized content can lag behind en-us, so its latest version url
136
+ * does include the version id. In that case, the first version in the
137
+ * list is the latest one.
138
+ **/
139
+ const currentGAVersion =
140
+ this.versionOptions.find(
141
+ (version) => !version.url.includes(version.id)
142
+ ) ?? this.versionOptions[0];
136
143
  if (currentGAVersion?.link?.href && this.version?.id) {
137
144
  const versionNo = currentGAVersion.id;
138
145
  /**
@@ -1,28 +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
- // encodeURI then keeps the value from breaking out of the href attribute.
7
- const toSafeHref = (link: string): string => {
8
- try {
9
- const { protocol } = new URL(link, window.location.origin);
10
- if (protocol === "http:" || protocol === "https:") {
11
- return encodeURI(link);
12
- }
13
- } catch {
14
- // Fall through to the rejection below.
15
- }
16
- console.warn(`Blocked unsafe version link: ${link}`);
17
- return "#";
18
- };
19
-
20
3
  export const oldVersionDocInfo = (latestVersionLink: string) => {
21
- const safeLink = toSafeHref(latestVersionLink);
22
4
  return {
23
5
  title: "Newer Version Available",
24
- body: `This content describes an older version of this product.
25
- <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>`
26
8
  };
27
9
  };
28
10