@salesforcedevs/docs-components 1.38.0-alpha.0 → 1.38.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.
@@ -1,7 +1,12 @@
1
- import { LightningElement, api } from "lwc";
1
+ import { LightningElement, api, track } from "lwc";
2
2
  import { toJson } from "dxUtils/normalizers";
3
- import { loadSidebar } from "docUtils/sidebarLoader";
4
- import type { OptionWithLink, TreeNode } from "typings/custom";
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";
5
10
 
6
11
  /**
7
12
  * Per-topic type emitted by the docs content-type parser
@@ -11,61 +16,48 @@ import type { OptionWithLink, TreeNode } from "typings/custom";
11
16
  */
12
17
  const TOPIC_TYPE_SPEC = "spec";
13
18
 
14
- /**
15
- * Walks down the first-child chain and returns the first markdown content
16
- * page found, descending through nested content-less parents. Returns
17
- * undefined if the chain breaks on a spec or external link before reaching a
18
- * content page.
19
- */
20
- function firstChildContentPage(node: TreeNode): TreeNode | undefined {
21
- const firstChild = node.children?.[0];
22
- if (!firstChild) {
23
- return undefined;
24
- }
25
-
26
- const isSpec =
27
- (firstChild as { topicType?: string }).topicType === TOPIC_TYPE_SPEC;
28
- const isExternal = firstChild.link?.target === "_blank";
29
- if (isSpec || isExternal) {
30
- return undefined;
31
- }
32
-
33
- if (firstChild.link?.href) {
34
- return firstChild;
35
- }
36
-
37
- return firstChildContentPage(firstChild);
38
- }
39
-
40
19
  /**
41
20
  * Translates per-topic `topicType` into the generic `showForwardArrow` flag
42
- * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc),
43
- * and redirects content-less parent topics whose first child is a content page
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.
44
26
  */
45
- function decorateTopics(
46
- topics: Array<TreeNode & { topicType?: string }> | undefined
27
+ function decorateTopicsWithForwardArrow(
28
+ topics:
29
+ | Array<TreeNode & { topicType?: string; versions?: unknown }>
30
+ | undefined
47
31
  ): TreeNode[] | undefined {
48
32
  return topics?.map((topic) => {
49
- const { topicType, ...decorated } = topic;
33
+ const { topicType, versions, ...decorated } = topic;
50
34
  if (topicType === TOPIC_TYPE_SPEC) {
51
35
  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
+ );
52
50
  }
53
51
  if (decorated.children) {
54
- decorated.children = decorateTopics(decorated.children);
52
+ decorated.children = decorateTopicsWithForwardArrow(
53
+ decorated.children
54
+ );
55
55
  }
56
56
 
57
- /** Redirect a parent that has no content of its own to its first child
58
- * but only when that first child is itself a content page
59
- */
60
- const isContentlessParent =
61
- !!decorated.children?.length && !decorated.link?.href;
62
-
63
- if (isContentlessParent) {
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) {
64
60
  decorated.redirectToChild = true;
65
- const firstChild = firstChildContentPage(topic);
66
- if (firstChild?.link) {
67
- decorated.link = { ...firstChild.link };
68
- }
69
61
  }
70
62
 
71
63
  return decorated;
@@ -102,6 +94,9 @@ export default class UnifiedContentLayout extends LightningElement {
102
94
 
103
95
  private _docPhaseInfo: string | null = null;
104
96
  private _sidebarContent: unknown = null;
97
+ private _oldVersionInfo: DocPhaseInfo | null = null;
98
+
99
+ @track showVersionBanner = false;
105
100
 
106
101
  @api
107
102
  get docPhaseInfo(): string | null {
@@ -118,61 +113,40 @@ export default class UnifiedContentLayout extends LightningElement {
118
113
  }
119
114
 
120
115
  set sidebarContent(value: string) {
121
- this._sidebarContent =
122
- value === "" ? null : decorateTopics(toJson(value)?.topics);
116
+ const topics = decorateTopicsWithForwardArrow(toJson(value)?.topics);
117
+ this._sidebarContent = topics;
118
+ this.updateTopicVersionBanner(topics as VersionedNode[] | undefined);
123
119
  }
124
120
 
125
- /**
126
- * URL of the left-nav JSON file, loaded when no inline `sidebarContent`
127
- * is set. Loaded here rather than in `doc-content-layout` so the topics
128
- * are decorated the same way as inline content.
129
- */
130
- @api
131
- get sidebarSrc(): string | undefined {
132
- return this._sidebarSrc;
121
+ get oldVersionInfo(): DocPhaseInfo | null {
122
+ return this._oldVersionInfo;
133
123
  }
134
124
 
135
- set sidebarSrc(value: string | undefined) {
136
- this._sidebarSrc = value || undefined;
137
- if (this.hasConnected) {
138
- this.loadSidebarContent();
139
- }
125
+ handleDismissVersionBanner(): void {
126
+ this.showVersionBanner = false;
140
127
  }
141
128
 
142
- private _sidebarSrc?: string;
143
- private isSidebarLoading = false;
144
- private hasConnected = false;
145
-
146
- connectedCallback(): void {
147
- this.hasConnected = true;
148
- this.loadSidebarContent();
149
- }
150
-
151
- disconnectedCallback(): void {
152
- this.hasConnected = false;
153
- }
154
-
155
- private loadSidebarContent(): void {
156
- const src = this._sidebarSrc;
157
- if (!src || this._sidebarContent) {
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;
158
145
  return;
159
146
  }
160
147
 
161
- this.isSidebarLoading = true;
162
- loadSidebar<Array<TreeNode & { topicType?: string }>>(src)
163
- .then(
164
- (topics) => {
165
- if (src === this._sidebarSrc && !this._sidebarContent) {
166
- this._sidebarContent = decorateTopics(topics);
167
- }
168
- },
169
- (error) => console.error(error)
170
- )
171
- .then(() => {
172
- if (src === this._sidebarSrc) {
173
- this.isSidebarLoading = false;
174
- }
175
- });
148
+ this._oldVersionInfo = null;
149
+ this.showVersionBanner = false;
176
150
  }
177
151
 
178
152
  private get enableFooter(): boolean {
@@ -24,7 +24,7 @@
24
24
  ondismissphase={handleDismissVersionBanner}
25
25
  ></doc-phase>
26
26
  <div lwc:if={showVersionPicker} slot="sidebar-header">
27
- <doc-version-picker
27
+ <dx-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
- ></doc-version-picker>
35
+ ></dx-version-picker>
36
36
  </div>
37
37
  <div class="breadcrumb-row" lwc:if={showBreadcrumbs}>
38
38
  <doc-breadcrumbs
@@ -1,10 +1,30 @@
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
+
3
22
  export const oldVersionDocInfo = (latestVersionLink: string) => {
23
+ const safeLink = toSafeHref(latestVersionLink);
4
24
  return {
5
25
  title: "Newer Version Available",
6
- body: `This content describes an older version of this product.
7
- <a style="font-weight: bold;" href="${latestVersionLink}">View Latest</a>`
26
+ body: `This content describes an older version of this product.
27
+ <a style="font-weight: bold;" href="${safeLink}">View Latest</a>`
8
28
  };
9
29
  };
10
30
 
@@ -1,64 +0,0 @@
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
- }
@@ -1,40 +0,0 @@
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>
@@ -1,65 +0,0 @@
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
- }
@@ -1,50 +0,0 @@
1
- /**
2
- * Loads the left-nav JSON that the doc framework writes once per content type
3
- * (`lnb.<hash>.json`) and references from each page as `sidebar-src`.
4
- */
5
-
6
- /** Schema version of the left-nav JSON files this loader understands. */
7
- export const SIDEBAR_SCHEMA_VERSION = 1;
8
-
9
- type SidebarFile<T> = { schemaVersion: number; topics: T };
10
-
11
- const requests = new Map<string, Promise<unknown>>();
12
-
13
- /**
14
- * Fetches the left-nav JSON at `src` and returns its `topics`.
15
- * Requests are shared per URL; a failed request is dropped so the next call
16
- * retries. The returned topics are shared between callers.
17
- */
18
- export function loadSidebar<T>(src: string): Promise<T> {
19
- let request = requests.get(src);
20
- if (!request) {
21
- request = fetch(src, { credentials: "same-origin" })
22
- .then((response) => {
23
- if (!response.ok) {
24
- throw new Error(
25
- `Failed to load the sidebar ${src}: ${response.status}`
26
- );
27
- }
28
- return response.json();
29
- })
30
- .then((file: SidebarFile<T>) => {
31
- if (file?.schemaVersion !== SIDEBAR_SCHEMA_VERSION) {
32
- throw new Error(
33
- `Unsupported sidebar schema version ${file?.schemaVersion} in ${src}`
34
- );
35
- }
36
- return file.topics;
37
- })
38
- .catch((error) => {
39
- requests.delete(src);
40
- throw error;
41
- });
42
- requests.set(src, request);
43
- }
44
- return request as Promise<T>;
45
- }
46
-
47
- /** Drops all cached requests. Used by tests. */
48
- export function clearSidebarRequests(): void {
49
- requests.clear();
50
- }