@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.
@@ -7,7 +7,6 @@
7
7
  sidebar-header={sidebarHeader}
8
8
  sidebar-value={sidebarValue}
9
9
  sidebar-content={sidebarContent}
10
- sidebar-loading={isSidebarLoading}
11
10
  toc-title={tocTitle}
12
11
  toc-options={tocOptions}
13
12
  toc-aria-level={tocAriaLevel}
@@ -20,11 +19,27 @@
20
19
  dev-center={devCenter}
21
20
  brand={brand}
22
21
  >
22
+ <div lwc:if={showProjectVersionPicker} slot="sidebar-header">
23
+ <dx-version-picker
24
+ onchange={handleProjectVersionChange}
25
+ versions={projectVersionOptions}
26
+ selected-version={selectedProjectVersion}
27
+ latest-version={isLatestProjectVersion}
28
+ ></dx-version-picker>
29
+ </div>
23
30
  <doc-phase
24
31
  slot="doc-phase"
25
32
  lwc:if={docPhaseInfo}
26
33
  doc-phase-info={docPhaseInfo}
27
34
  ></doc-phase>
35
+ <doc-phase
36
+ slot="version-banner"
37
+ lwc:if={showVersionBanner}
38
+ doc-phase-info={oldVersionInfo}
39
+ icon-name="warning"
40
+ dismissible="true"
41
+ ondismissphase={handleDismissVersionBanner}
42
+ ></doc-phase>
28
43
  <slot></slot>
29
44
  </doc-content-layout>
30
45
  </template>
@@ -1,7 +1,30 @@
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 {
4
+ ProjectVersionPicker,
5
+ TopicVersionOption,
6
+ VersionedNode
7
+ } from "dxUtils/topicVersion";
8
+ import {
9
+ findTopicVersionForCurrentPage,
10
+ hrefMatchesCurrentPage,
11
+ latestHrefForCurrentPage,
12
+ normalizePath,
13
+ persistTopicVersion,
14
+ projectVersionForCurrentPage,
15
+ projectVersionKey,
16
+ projectVersionOptions,
17
+ resolveProjectVersion,
18
+ toProjectVersionPicker
19
+ } from "dxUtils/topicVersion";
20
+ import { oldVersionDocInfo } from "docUtils/utils";
21
+ import type { DocPhaseInfo, OptionWithLink, TreeNode } from "typings/custom";
22
+
23
+ type SidebarPayload = {
24
+ topics?: Array<TreeNode & { topicType?: string; versions?: unknown }>;
25
+ versions?: TopicVersionOption[];
26
+ versionTopicSessionKey?: string;
27
+ };
5
28
 
6
29
  /**
7
30
  * Per-topic type emitted by the docs content-type parser
@@ -11,61 +34,48 @@ import type { OptionWithLink, TreeNode } from "typings/custom";
11
34
  */
12
35
  const TOPIC_TYPE_SPEC = "spec";
13
36
 
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
37
  /**
41
38
  * 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
39
+ * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc).
40
+ *
41
+ * Content-less parents are flagged with redirectToChild and left without a
42
+ * link. The tree selects the first markdown descendant. Copying that child's
43
+ * href onto the parent makes the parent win selection.
44
44
  */
45
- function decorateTopics(
46
- topics: Array<TreeNode & { topicType?: string }> | undefined
45
+ function decorateTopicsWithForwardArrow(
46
+ topics:
47
+ | Array<TreeNode & { topicType?: string; versions?: unknown }>
48
+ | undefined
47
49
  ): TreeNode[] | undefined {
48
50
  return topics?.map((topic) => {
49
- const { topicType, ...decorated } = topic;
51
+ const { topicType, versions, ...decorated } = topic;
50
52
  if (topicType === TOPIC_TYPE_SPEC) {
51
53
  decorated.showForwardArrow = true;
54
+ // Nested and standalone specs never get a sidebar picker; only the
55
+ // parent MD topic (when versioned) shows one.
56
+ } else if (Array.isArray(versions)) {
57
+ decorated.versions = versions.map(
58
+ (version: { children?: TreeNode[] }) =>
59
+ version.children
60
+ ? {
61
+ ...version,
62
+ children: decorateTopicsWithForwardArrow(
63
+ version.children
64
+ )
65
+ }
66
+ : version
67
+ );
52
68
  }
53
69
  if (decorated.children) {
54
- decorated.children = decorateTopics(decorated.children);
70
+ decorated.children = decorateTopicsWithForwardArrow(
71
+ decorated.children
72
+ );
55
73
  }
56
74
 
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) {
75
+ // Flag a parent with no page of its own. Leave its link empty so the
76
+ // child's URL stays indexed to the child.
77
+ if (!!decorated.children?.length && !decorated.link?.href) {
64
78
  decorated.redirectToChild = true;
65
- const firstChild = firstChildContentPage(topic);
66
- if (firstChild?.link) {
67
- decorated.link = { ...firstChild.link };
68
- }
69
79
  }
70
80
 
71
81
  return decorated;
@@ -102,6 +112,11 @@ export default class UnifiedContentLayout extends LightningElement {
102
112
 
103
113
  private _docPhaseInfo: string | null = null;
104
114
  private _sidebarContent: unknown = null;
115
+ private _oldVersionInfo: DocPhaseInfo | null = null;
116
+ private _projectPicker: ProjectVersionPicker | undefined;
117
+ private _viewLatestAnchor: HTMLAnchorElement | null = null;
118
+
119
+ @track showVersionBanner = false;
105
120
 
106
121
  @api
107
122
  get docPhaseInfo(): string | null {
@@ -112,70 +127,206 @@ export default class UnifiedContentLayout extends LightningElement {
112
127
  this._docPhaseInfo = value || null;
113
128
  }
114
129
 
130
+ /**
131
+ * `dxSideBarContents`. Only `topics` goes to the tree. A project-versioned
132
+ * project also sends `versions` and `versionTopicSessionKey` for the one
133
+ * project picker in the sidebar header.
134
+ */
115
135
  @api
116
136
  get sidebarContent(): unknown {
117
137
  return this._sidebarContent;
118
138
  }
119
139
 
120
140
  set sidebarContent(value: string) {
121
- this._sidebarContent =
122
- value === "" ? null : decorateTopics(toJson(value)?.topics);
141
+ const payload = toJson(value) as SidebarPayload | null;
142
+ const topics = decorateTopicsWithForwardArrow(payload?.topics);
143
+ this._sidebarContent = topics;
144
+ this._projectPicker = toProjectVersionPicker(payload);
145
+ this.updateVersionBanner(topics as VersionedNode[] | undefined);
146
+ }
147
+
148
+ connectedCallback(): void {
149
+ this.syncProjectVersionSession();
150
+ }
151
+
152
+ renderedCallback(): void {
153
+ this.bindViewLatestLink(this.projectViewLatestLink());
154
+ }
155
+
156
+ disconnectedCallback(): void {
157
+ this.bindViewLatestLink(null);
158
+ }
159
+
160
+ get showProjectVersionPicker(): boolean {
161
+ return (this._projectPicker?.versions.length ?? 0) > 1;
162
+ }
163
+
164
+ get projectVersionOptions(): TopicVersionOption[] | undefined {
165
+ return projectVersionOptions(this._projectPicker);
166
+ }
167
+
168
+ get selectedProjectVersion(): TopicVersionOption | undefined {
169
+ const selected = this.resolvedProjectVersion;
170
+ return this.projectVersionOptions?.find(
171
+ (option) => option.id === selected?.id
172
+ );
173
+ }
174
+
175
+ get isLatestProjectVersion(): boolean {
176
+ const latest = this._projectPicker?.versions[0];
177
+ return !!latest && this.resolvedProjectVersion?.id === latest.id;
178
+ }
179
+
180
+ get oldVersionInfo(): DocPhaseInfo | null {
181
+ return this._oldVersionInfo;
182
+ }
183
+
184
+ handleDismissVersionBanner(): void {
185
+ this.showVersionBanner = false;
123
186
  }
124
187
 
125
188
  /**
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.
189
+ * Remember the choice for the whole project, then load that version's
190
+ * copy of this page so the server sends that version's topics.
129
191
  */
130
- @api
131
- get sidebarSrc(): string | undefined {
132
- return this._sidebarSrc;
192
+ handleProjectVersionChange(event: CustomEvent): void {
193
+ const versionId = event.detail ? String(event.detail) : "";
194
+ const option = this._projectPicker?.versions.find(
195
+ (version) => version.id === versionId
196
+ );
197
+ if (!option) {
198
+ return;
199
+ }
200
+ this.persistProjectVersion(option.id);
201
+ const href = option.link?.href;
202
+ if (href && !hrefMatchesCurrentPage(href)) {
203
+ window.location.assign(href);
204
+ }
133
205
  }
134
206
 
135
- set sidebarSrc(value: string | undefined) {
136
- this._sidebarSrc = value || undefined;
137
- if (this.hasConnected) {
138
- this.loadSidebarContent();
207
+ private get resolvedProjectVersion(): TopicVersionOption | undefined {
208
+ return resolveProjectVersion(this._projectPicker, this.language);
209
+ }
210
+
211
+ private persistProjectVersion(versionId: string): void {
212
+ const key = projectVersionKey(this._projectPicker, this.language);
213
+ if (key) {
214
+ persistTopicVersion(key, versionId);
139
215
  }
140
216
  }
141
217
 
142
- private _sidebarSrc?: string;
143
- private isSidebarLoading = false;
144
- private hasConnected = false;
218
+ /**
219
+ * A page whose URL is one of the options records that version for the
220
+ * project. Other pages leave the session alone. The project root serves
221
+ * the latest tree, so a stored older version opens its own landing page
222
+ * there instead of showing that version over the latest topics.
223
+ */
224
+ private syncProjectVersionSession(): void {
225
+ const picker = this._projectPicker;
226
+ if (!picker || typeof window === "undefined") {
227
+ return;
228
+ }
229
+ const fromUrl = projectVersionForCurrentPage(picker);
230
+ if (fromUrl) {
231
+ this.persistProjectVersion(fromUrl.id);
232
+ return;
233
+ }
234
+ if (
235
+ normalizePath(window.location.pathname) !==
236
+ normalizePath(picker.sessionKey)
237
+ ) {
238
+ return;
239
+ }
240
+ const stored = this.resolvedProjectVersion;
241
+ const href = stored?.link?.href;
242
+ if (
243
+ stored &&
244
+ !stored.selected &&
245
+ href &&
246
+ !hrefMatchesCurrentPage(href)
247
+ ) {
248
+ window.location.replace(href);
249
+ }
250
+ }
145
251
 
146
- connectedCallback(): void {
147
- this.hasConnected = true;
148
- this.loadSidebarContent();
252
+ /**
253
+ * Same banner references use when the reader is on an older version. A
254
+ * project version takes precedence; otherwise the topic version the URL
255
+ * selects in the tree decides.
256
+ */
257
+ private updateVersionBanner(topics: VersionedNode[] | undefined): void {
258
+ const info =
259
+ this.projectOldVersionInfo() ?? topicOldVersionInfo(topics);
260
+ this._oldVersionInfo = info;
261
+ this.showVersionBanner = !!info;
149
262
  }
150
263
 
151
- disconnectedCallback(): void {
152
- this.hasConnected = false;
264
+ private projectOldVersionInfo(): DocPhaseInfo | null {
265
+ const latest = this._projectPicker?.versions[0];
266
+ const selected = this.resolvedProjectVersion;
267
+ const latestHref = latest?.link?.href;
268
+ if (!latest || !selected || selected.id === latest.id || !latestHref) {
269
+ return null;
270
+ }
271
+ return oldVersionDocInfo(latestHref);
153
272
  }
154
273
 
155
- private loadSidebarContent(): void {
156
- const src = this._sidebarSrc;
157
- if (!src || this._sidebarContent) {
158
- return;
274
+ /**
275
+ * The View Latest link is innerHTML inside the banner's doc-phase. Bind it
276
+ * directly so the latest id is stored before the page changes; the next
277
+ * page may not be one whose URL names a version.
278
+ */
279
+ private projectViewLatestLink(): HTMLAnchorElement | null {
280
+ if (!this._projectPicker || !this.showVersionBanner) {
281
+ return null;
159
282
  }
283
+ const banner = this.template.querySelector(
284
+ 'doc-phase[slot="version-banner"]'
285
+ );
286
+ return banner?.shadowRoot?.querySelector("a") ?? null;
287
+ }
160
288
 
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
- });
289
+ private bindViewLatestLink(anchor: HTMLAnchorElement | null): void {
290
+ if (this._viewLatestAnchor === anchor) {
291
+ return;
292
+ }
293
+ this._viewLatestAnchor?.removeEventListener(
294
+ "click",
295
+ this.handleViewLatestClick
296
+ );
297
+ this._viewLatestAnchor = anchor;
298
+ anchor?.addEventListener("click", this.handleViewLatestClick);
176
299
  }
177
300
 
301
+ private handleViewLatestClick = (event: Event): void => {
302
+ const latest = this._projectPicker?.versions[0];
303
+ const href = (event.currentTarget as HTMLAnchorElement | null)?.href;
304
+ if (!latest || !href) {
305
+ return;
306
+ }
307
+ event.preventDefault();
308
+ this.persistProjectVersion(latest.id);
309
+ window.location.assign(href);
310
+ };
311
+
178
312
  private get enableFooter(): boolean {
179
313
  return !this.hideFooter;
180
314
  }
181
315
  }
316
+
317
+ /**
318
+ * Topic-level banner. Topic versions are not a separate page property: the
319
+ * sidebar tree carries each version's switching URL, and the current pathname
320
+ * says which one is open.
321
+ */
322
+ function topicOldVersionInfo(
323
+ topics: VersionedNode[] | undefined
324
+ ): DocPhaseInfo | null {
325
+ const match = findTopicVersionForCurrentPage(topics);
326
+ const latest = match?.node.versions?.[0];
327
+ const latestHref = latestHrefForCurrentPage(match?.node.versions);
328
+ if (match && latest && match.version.id !== latest.id && latestHref) {
329
+ return oldVersionDocInfo(latestHref);
330
+ }
331
+ return null;
332
+ }
@@ -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
- }