@salesforcedevs/docs-components 1.38.0-node24-1 → 1.38.0-plv-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@salesforcedevs/docs-components",
3
- "version": "1.38.0-node24-1",
3
+ "version": "1.38.0-plv-alpha",
4
4
  "description": "Docs Lightning web components for DSC",
5
5
  "license": "MIT",
6
6
  "main": "index.js",
7
7
  "engines": {
8
- "node": "24.x"
8
+ "node": "22.x"
9
9
  },
10
10
  "publishConfig": {
11
11
  "access": "public"
@@ -17,12 +17,23 @@ import {
17
17
  DOCS_PATH_SEGMENT,
18
18
  normalizePath,
19
19
  getTopicVersionKey,
20
+ hrefMatchesCurrentPage,
20
21
  getVersionPickerOptions,
21
22
  persistTopicVersion,
23
+ projectHrefForVersion,
24
+ projectVersionForCurrentPage,
25
+ projectVersionKey,
26
+ projectVersionOptions,
22
27
  REFERENCES_LOCALE_SEGMENT_INDEX,
23
- toCanonicalHref
28
+ resolveProjectVersion,
29
+ toCanonicalHref,
30
+ toProjectVersionPicker
31
+ } from "dxUtils/topicVersion";
32
+ import type {
33
+ ProjectVersionPicker,
34
+ TopicVersionOption,
35
+ VersionedNode
24
36
  } from "dxUtils/topicVersion";
25
- import type { VersionedNode } from "dxUtils/topicVersion";
26
37
  import type { DocPhaseInfo, OptionWithLink } from "typings/custom";
27
38
 
28
39
  declare global {
@@ -64,6 +75,13 @@ type ReferenceConfig = {
64
75
  versionTopicSessionKey?: string;
65
76
  };
66
77
 
78
+ /** `versionedTopicTree`: the spec's versioned topic, plus a project picker when sent. */
79
+ type VersionedTopicTree = {
80
+ topics?: VersionedNode[];
81
+ versions?: TopicVersionOption[];
82
+ versionTopicSessionKey?: string;
83
+ };
84
+
67
85
  const SCROLL_THROTTLE_DELAY = 50;
68
86
  const ELEMENT_TIMEOUT = 10000;
69
87
  const ELEMENT_CHECK_INTERVAL = 100;
@@ -150,14 +168,14 @@ export default class RedocReference extends LightningElement {
150
168
  * in the path.
151
169
  */
152
170
  @api
153
- set versionedTopicTree(
154
- value: string | { topics?: VersionedNode[] } | null
155
- ) {
171
+ set versionedTopicTree(value: string | VersionedTopicTree | null) {
156
172
  try {
157
- const parsed = toJson(value) as { topics?: VersionedNode[] } | null;
173
+ const parsed = toJson(value) as VersionedTopicTree | null;
158
174
  this._versionedTopicNode = parsed?.topics?.[0] ?? null;
175
+ this._treeProjectPicker = toProjectVersionPicker(parsed);
159
176
  } catch (error) {
160
177
  this._versionedTopicNode = null;
178
+ this._treeProjectPicker = undefined;
161
179
  }
162
180
  this.refreshVersions();
163
181
  }
@@ -169,6 +187,22 @@ export default class RedocReference extends LightningElement {
169
187
  }
170
188
 
171
189
  private _versionedTopicNode: VersionedNode | null = null;
190
+ private _treeProjectPicker: ProjectVersionPicker | undefined;
191
+
192
+ /**
193
+ * Project-level picker shared with the markdown sidebar. Read from the
194
+ * tree payload when it carries one, else from `referenceConfig`. A spec
195
+ * with its own topic-level versions keeps that picker instead.
196
+ */
197
+ private get projectPicker(): ProjectVersionPicker | undefined {
198
+ if (this._treeProjectPicker) {
199
+ return this._treeProjectPicker;
200
+ }
201
+ if (this._versionedTopicNode?.versions?.length) {
202
+ return undefined;
203
+ }
204
+ return toProjectVersionPicker(this._referenceConfig);
205
+ }
172
206
 
173
207
  @api
174
208
  get contentType(): string {
@@ -218,6 +252,14 @@ export default class RedocReference extends LightningElement {
218
252
  * URL is already set by then and does not change for this instance.
219
253
  */
220
254
  private refreshVersions(): void {
255
+ // Project options already point at this spec in every version.
256
+ const projectPicker = this.projectPicker;
257
+ if (projectPicker) {
258
+ this._versions = (projectVersionOptions(projectPicker) ??
259
+ []) as ReferenceVersion[];
260
+ return;
261
+ }
262
+
221
263
  const versions = this._referenceConfig?.versions ?? [];
222
264
  const node = this._versionedTopicNode;
223
265
  if (!node?.versions?.length || typeof window === "undefined") {
@@ -246,9 +288,21 @@ export default class RedocReference extends LightningElement {
246
288
  });
247
289
  }
248
290
 
249
- /** The version flagged `selected`, else the first (the latest/GA version). */
291
+ /**
292
+ * Project versions: the open URL, then the project session, then
293
+ * `selected`, matching the markdown sidebar. Otherwise the version
294
+ * flagged `selected`, else the first (the latest/GA version).
295
+ */
250
296
  get selectedVersion(): ReferenceVersion | null {
251
297
  const versions = this.versions;
298
+ const projectPicker = this.projectPicker;
299
+ if (projectPicker) {
300
+ const resolved = resolveProjectVersion(
301
+ projectPicker,
302
+ this.language ?? undefined
303
+ );
304
+ return versions.find((v) => v.id === resolved?.id) ?? null;
305
+ }
252
306
  return versions.find((v) => v.selected) ?? versions[0] ?? null;
253
307
  }
254
308
 
@@ -337,6 +391,22 @@ export default class RedocReference extends LightningElement {
337
391
  return target;
338
392
  }
339
393
 
394
+ // Project versions cover every page in the project, so any project
395
+ // page goes back on the selected version, like a topic family does
396
+ // below. Otherwise the stored page keeps the version it was opened
397
+ // on and the markdown sidebar switches back to it.
398
+ const projectPicker = this.projectPicker;
399
+ if (projectPicker) {
400
+ const versioned = projectHrefForVersion(
401
+ targetUrl.pathname,
402
+ projectPicker,
403
+ selectedVersion.id
404
+ );
405
+ return versioned
406
+ ? `${versioned}${targetUrl.search}${targetUrl.hash}`
407
+ : target;
408
+ }
409
+
340
410
  // The spec picker links can use a different file name in each version
341
411
  // (`sample-api` and `new-sample-api`). That pair cannot move a sibling
342
412
  // page between versions. The parent topic's switching URLs share one
@@ -517,10 +587,14 @@ export default class RedocReference extends LightningElement {
517
587
  this.trackBackTarget();
518
588
 
519
589
  // Remember the selected version for the sidebar. Changing version
520
- // reloads this page.
590
+ // reloads this page. A project picker stores only a version the URL
591
+ // names, so it never overwrites the reader's choice with a fallback.
521
592
  const topicKey = this.getParentTopicVersionKey();
522
- if (topicKey && this.selectedVersion) {
523
- persistTopicVersion(topicKey, this.selectedVersion.id);
593
+ const versionToStore = this.projectPicker
594
+ ? projectVersionForCurrentPage(this.projectPicker)
595
+ : this.selectedVersion;
596
+ if (topicKey && versionToStore) {
597
+ persistTopicVersion(topicKey, versionToStore.id);
524
598
  }
525
599
 
526
600
  window.addEventListener("scroll", this.handleScrollAndResize);
@@ -535,6 +609,7 @@ export default class RedocReference extends LightningElement {
535
609
  }
536
610
 
537
611
  disconnectedCallback(): void {
612
+ this.bindViewLatestLink(null);
538
613
  window.removeEventListener("scroll", this.handleScrollAndResize);
539
614
  window.removeEventListener("resize", this.handleScrollAndResize);
540
615
 
@@ -836,6 +911,13 @@ export default class RedocReference extends LightningElement {
836
911
  * Missing `versionTopicSessionKey` returns null so nothing is written.
837
912
  */
838
913
  private getParentTopicVersionKey(): string | null {
914
+ const projectPicker = this.projectPicker;
915
+ if (projectPicker) {
916
+ return (
917
+ projectVersionKey(projectPicker, this.language ?? undefined) ||
918
+ null
919
+ );
920
+ }
839
921
  const versionTopicSessionKey =
840
922
  this._referenceConfig?.versionTopicSessionKey;
841
923
  if (!versionTopicSessionKey) {
@@ -849,12 +931,61 @@ export default class RedocReference extends LightningElement {
849
931
  );
850
932
  }
851
933
 
852
- /** Stashes the current view (URL hash) before the version link navigates. */
853
- private onVersionChange = (): void => {
934
+ /**
935
+ * Stashes the current view (URL hash) before the version link navigates.
936
+ * A project version is also stored for the project and opened by href,
937
+ * so the markdown sidebar shows the same version afterwards.
938
+ */
939
+ private onVersionChange = (event?: CustomEvent): void => {
854
940
  sessionStorage.setItem(
855
941
  SELECTED_VIEW_STORAGE_KEY,
856
942
  window.location.hash || ""
857
943
  );
944
+ if (!this.projectPicker) {
945
+ return;
946
+ }
947
+ const versionId = event?.detail ? String(event.detail) : "";
948
+ const option = this.versions.find((v) => v.id === versionId);
949
+ const topicKey = this.getParentTopicVersionKey();
950
+ if (!option || !topicKey) {
951
+ return;
952
+ }
953
+ persistTopicVersion(topicKey, option.id);
954
+ const href = option.link?.href;
955
+ if (href && !hrefMatchesCurrentPage(href)) {
956
+ window.location.assign(href);
957
+ }
958
+ };
959
+
960
+ private _viewLatestAnchor: HTMLAnchorElement | null = null;
961
+
962
+ /**
963
+ * View Latest is innerHTML inside the banner's doc-phase. For a project
964
+ * picker, store the latest id before leaving so every page in the project
965
+ * opens on latest.
966
+ */
967
+ private bindViewLatestLink(anchor: HTMLAnchorElement | null): void {
968
+ if (this._viewLatestAnchor === anchor) {
969
+ return;
970
+ }
971
+ this._viewLatestAnchor?.removeEventListener(
972
+ "click",
973
+ this.handleViewLatestClick
974
+ );
975
+ this._viewLatestAnchor = anchor;
976
+ anchor?.addEventListener("click", this.handleViewLatestClick);
977
+ }
978
+
979
+ private handleViewLatestClick = (event: Event): void => {
980
+ const latest = this.versions[0];
981
+ const topicKey = this.getParentTopicVersionKey();
982
+ const href = (event.currentTarget as HTMLAnchorElement | null)?.href;
983
+ if (!latest || !topicKey || !href) {
984
+ return;
985
+ }
986
+ event.preventDefault();
987
+ persistTopicVersion(topicKey, latest.id);
988
+ window.location.assign(href);
858
989
  };
859
990
 
860
991
  /**
@@ -998,6 +1129,11 @@ export default class RedocReference extends LightningElement {
998
1129
  this.updateSidebarPosition();
999
1130
  });
1000
1131
  wrapper.appendChild(versionBanner);
1132
+ if (this.projectPicker) {
1133
+ this.bindViewLatestLink(
1134
+ versionBanner.shadowRoot?.querySelector("a") ?? null
1135
+ );
1136
+ }
1001
1137
  }
1002
1138
  }
1003
1139
 
@@ -19,6 +19,14 @@
19
19
  dev-center={devCenter}
20
20
  brand={brand}
21
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>
22
30
  <doc-phase
23
31
  slot="doc-phase"
24
32
  lwc:if={docPhaseInfo}
@@ -1,13 +1,31 @@
1
1
  import { LightningElement, api, track } from "lwc";
2
2
  import { toJson } from "dxUtils/normalizers";
3
- import type { VersionedNode } from "dxUtils/topicVersion";
3
+ import type {
4
+ ProjectVersionPicker,
5
+ TopicVersionOption,
6
+ VersionedNode
7
+ } from "dxUtils/topicVersion";
4
8
  import {
5
9
  findTopicVersionForCurrentPage,
6
- latestHrefForCurrentPage
10
+ hrefMatchesCurrentPage,
11
+ latestHrefForCurrentPage,
12
+ normalizePath,
13
+ persistTopicVersion,
14
+ projectVersionForCurrentPage,
15
+ projectVersionKey,
16
+ projectVersionOptions,
17
+ resolveProjectVersion,
18
+ toProjectVersionPicker
7
19
  } from "dxUtils/topicVersion";
8
20
  import { oldVersionDocInfo } from "docUtils/utils";
9
21
  import type { DocPhaseInfo, OptionWithLink, TreeNode } from "typings/custom";
10
22
 
23
+ type SidebarPayload = {
24
+ topics?: Array<TreeNode & { topicType?: string; versions?: unknown }>;
25
+ versions?: TopicVersionOption[];
26
+ versionTopicSessionKey?: string;
27
+ };
28
+
11
29
  /**
12
30
  * Per-topic type emitted by the docs content-type parser
13
31
  * (see @salesforcedevs/sfdocs-doc-framework: `TopicTypeEnum`). Only `spec`
@@ -95,6 +113,8 @@ export default class UnifiedContentLayout extends LightningElement {
95
113
  private _docPhaseInfo: string | null = null;
96
114
  private _sidebarContent: unknown = null;
97
115
  private _oldVersionInfo: DocPhaseInfo | null = null;
116
+ private _projectPicker: ProjectVersionPicker | undefined;
117
+ private _viewLatestAnchor: HTMLAnchorElement | null = null;
98
118
 
99
119
  @track showVersionBanner = false;
100
120
 
@@ -107,15 +127,54 @@ export default class UnifiedContentLayout extends LightningElement {
107
127
  this._docPhaseInfo = value || null;
108
128
  }
109
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
+ */
110
135
  @api
111
136
  get sidebarContent(): unknown {
112
137
  return this._sidebarContent;
113
138
  }
114
139
 
115
140
  set sidebarContent(value: string) {
116
- const topics = decorateTopicsWithForwardArrow(toJson(value)?.topics);
141
+ const payload = toJson(value) as SidebarPayload | null;
142
+ const topics = decorateTopicsWithForwardArrow(payload?.topics);
117
143
  this._sidebarContent = topics;
118
- this.updateTopicVersionBanner(topics as VersionedNode[] | undefined);
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;
119
178
  }
120
179
 
121
180
  get oldVersionInfo(): DocPhaseInfo | null {
@@ -127,29 +186,147 @@ export default class UnifiedContentLayout extends LightningElement {
127
186
  }
128
187
 
129
188
  /**
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.
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.
134
191
  */
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;
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) {
145
198
  return;
146
199
  }
200
+ this.persistProjectVersion(option.id);
201
+ const href = option.link?.href;
202
+ if (href && !hrefMatchesCurrentPage(href)) {
203
+ window.location.assign(href);
204
+ }
205
+ }
147
206
 
148
- this._oldVersionInfo = null;
149
- this.showVersionBanner = false;
207
+ private get resolvedProjectVersion(): TopicVersionOption | undefined {
208
+ return resolveProjectVersion(this._projectPicker, this.language);
150
209
  }
151
210
 
211
+ private persistProjectVersion(versionId: string): void {
212
+ const key = projectVersionKey(this._projectPicker, this.language);
213
+ if (key) {
214
+ persistTopicVersion(key, versionId);
215
+ }
216
+ }
217
+
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
+ }
251
+
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;
262
+ }
263
+
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);
272
+ }
273
+
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;
282
+ }
283
+ const banner = this.template.querySelector(
284
+ 'doc-phase[slot="version-banner"]'
285
+ );
286
+ return banner?.shadowRoot?.querySelector("a") ?? null;
287
+ }
288
+
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);
299
+ }
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
+
152
312
  private get enableFooter(): boolean {
153
313
  return !this.hideFooter;
154
314
  }
155
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
+ }