@salesforcedevs/docs-components 1.35.1-remediation.1 → 1.36.0-alpha.0

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,6 +1,6 @@
1
1
  {
2
2
  "name": "@salesforcedevs/docs-components",
3
- "version": "1.35.1-remediation.1",
3
+ "version": "1.36.0-alpha.0",
4
4
  "description": "Docs Lightning web components for DSC",
5
5
  "license": "MIT",
6
6
  "main": "index.js",
@@ -29,6 +29,7 @@ import {
29
29
  import { restoreScroll } from "dx/scrollManager";
30
30
  import { DocPhaseInfo } from "typings/custom";
31
31
  import { oldVersionDocInfo } from "docUtils/utils";
32
+ import { loadSidebar } from "docUtils/sidebarLoader";
32
33
  import { track as trackEvent } from "dxUtils/analytics";
33
34
 
34
35
  type NavigationItem = {
@@ -100,6 +101,7 @@ export default class AmfReference extends LightningElement {
100
101
  };
101
102
  }
102
103
 
104
+ this.markdownTopicsPromise = undefined;
103
105
  this._amfConfigList = this._referenceSetConfig.refList || [];
104
106
 
105
107
  this._amfConfigList.forEach((amfConfig) => {
@@ -164,6 +166,20 @@ export default class AmfReference extends LightningElement {
164
166
  this._expandChildren = normalizeBoolean(value);
165
167
  }
166
168
 
169
+ /**
170
+ * URL of the left-nav JSON file with the topic trees of the markdown
171
+ * references, used when the reference set config omits them.
172
+ */
173
+ @api
174
+ get sidebarSrc(): string | undefined {
175
+ return this._sidebarSrc;
176
+ }
177
+
178
+ set sidebarSrc(value: string | undefined) {
179
+ this._sidebarSrc = value || undefined;
180
+ this.loadMarkdownTopics();
181
+ }
182
+
167
183
  private get enableFooter(): boolean {
168
184
  return !this.hideFooter;
169
185
  }
@@ -196,6 +212,9 @@ export default class AmfReference extends LightningElement {
196
212
  private isParentLevelDocPhaseEnabled = false;
197
213
  private selectedReferenceDocPhase?: string | null = null;
198
214
  private _expandChildren?: boolean = false;
215
+ private _sidebarSrc?: string;
216
+ /** Set while the markdown reference topics load from `sidebarSrc`. */
217
+ private markdownTopicsPromise?: Promise<void>;
199
218
  private isVersionFetched = false;
200
219
  private latestVersion = false;
201
220
 
@@ -399,6 +418,7 @@ export default class AmfReference extends LightningElement {
399
418
  if (this._amfConfigList && this._amfConfigList.length) {
400
419
  // fetch AMF Json as soon as config is set
401
420
  this.populateReferenceItems();
421
+ this.loadMarkdownTopics();
402
422
  // update() must be called after renderedCallback.
403
423
  if (this.hasRendered) {
404
424
  this.updateView();
@@ -481,16 +501,7 @@ export default class AmfReference extends LightningElement {
481
501
  isChildrenLoading = true;
482
502
  }
483
503
  } else {
484
- const isExpandChildrenEnabled = this.isExpandChildrenEnabled(
485
- amfConfig.id
486
- );
487
- // check whether we should expand all the child nodes, this is required for Coveo to crawl.
488
- if (isExpandChildrenEnabled) {
489
- this.expandChildrenForMarkdownReferences(
490
- amfConfig.topic!.children
491
- );
492
- }
493
- navItemChildren = amfConfig.topic!.children;
504
+ navItemChildren = this.getMarkdownNavItemChildren(amfConfig);
494
505
  }
495
506
  // store nav items for each spec in order
496
507
  navAmfOrder[index] = {
@@ -508,6 +519,118 @@ export default class AmfReference extends LightningElement {
508
519
  this.navigation = navAmfOrder;
509
520
  }
510
521
 
522
+ /**
523
+ * Returns the sidebar children of a markdown reference, expanded when
524
+ * expand children is enabled for it.
525
+ */
526
+ private getMarkdownNavItemChildren(
527
+ amfConfig: AmfConfig
528
+ ): ParsedMarkdownTopic[] {
529
+ // check whether we should expand all the child nodes, this is required for Coveo to crawl.
530
+ if (this.isExpandChildrenEnabled(amfConfig.id)) {
531
+ this.expandChildrenForMarkdownReferences(amfConfig.topic!.children);
532
+ }
533
+ return amfConfig.topic!.children;
534
+ }
535
+
536
+ /**
537
+ * Loads the topic trees of the markdown references from `sidebarSrc`
538
+ * when the reference set config does not include them.
539
+ */
540
+ private loadMarkdownTopics(): void {
541
+ const src = this._sidebarSrc;
542
+ const referenceSetConfig = this._referenceSetConfig;
543
+ const pendingIds = this._amfConfigList
544
+ .filter(
545
+ (amfConfig) =>
546
+ amfConfig.referenceType === REFERENCE_TYPES.markdown &&
547
+ !amfConfig.topic?.children?.length
548
+ )
549
+ .map((amfConfig) => amfConfig.id);
550
+ if (!src || !pendingIds.length || this.markdownTopicsPromise) {
551
+ return;
552
+ }
553
+
554
+ this.updateMarkdownNavItems(pendingIds, true);
555
+ this.markdownTopicsPromise = loadSidebar<
556
+ Record<string, ParsedMarkdownTopic>
557
+ >(src)
558
+ .then(
559
+ (topics) => {
560
+ if (referenceSetConfig !== this._referenceSetConfig) {
561
+ return;
562
+ }
563
+ // the config can be read-only, so replace the entries with copies
564
+ this._amfConfigList = this._amfConfigList.map(
565
+ (amfConfig) => {
566
+ const topic = pendingIds.includes(amfConfig.id)
567
+ ? topics[amfConfig.id]
568
+ : undefined;
569
+ if (!topic?.children) {
570
+ return amfConfig;
571
+ }
572
+ const loadedConfig = {
573
+ ...amfConfig,
574
+ topic: amfConfig.topic
575
+ ? {
576
+ ...amfConfig.topic,
577
+ children: topic.children
578
+ }
579
+ : topic
580
+ };
581
+ this._amfConfigMap.set(amfConfig.id, loadedConfig);
582
+ return loadedConfig;
583
+ }
584
+ );
585
+ },
586
+ (error) => console.error(error)
587
+ )
588
+ .then(() => {
589
+ if (referenceSetConfig !== this._referenceSetConfig) {
590
+ return;
591
+ }
592
+ this.markdownTopicsPromise = undefined;
593
+ this.updateMarkdownNavItems(pendingIds, false);
594
+ });
595
+ }
596
+
597
+ /**
598
+ * Rebuilds the sidebar items of the given markdown references.
599
+ */
600
+ private updateMarkdownNavItems(
601
+ referenceIds: string[],
602
+ isChildrenLoading: boolean
603
+ ): void {
604
+ this.navigation = this.navigation.map((navItem, index) => {
605
+ const amfConfig = this._amfConfigList[index];
606
+ return referenceIds.includes(amfConfig.id)
607
+ ? {
608
+ ...navItem,
609
+ children: this.getMarkdownNavItemChildren(amfConfig),
610
+ isChildrenLoading
611
+ }
612
+ : navItem;
613
+ });
614
+ }
615
+
616
+ /**
617
+ * Runs the callback once the markdown reference topics are loaded, or
618
+ * right away when they are not loading.
619
+ */
620
+ private afterMarkdownTopics(callback: () => void): void {
621
+ const promise = this.markdownTopicsPromise;
622
+ if (!promise) {
623
+ callback();
624
+ return;
625
+ }
626
+ const referenceSetConfig = this._referenceSetConfig;
627
+ promise.then(() => {
628
+ if (referenceSetConfig === this._referenceSetConfig) {
629
+ callback();
630
+ }
631
+ });
632
+ }
633
+
511
634
  /**
512
635
  * Determines whether the sidebar tile should render a forward arrow for
513
636
  * this reference. Honors `redoc` set on the config, and also infers it
@@ -929,7 +1052,7 @@ export default class AmfReference extends LightningElement {
929
1052
  );
930
1053
  }
931
1054
  } else {
932
- this.loadMarkdownBasedReference();
1055
+ this.afterMarkdownTopics(() => this.loadMarkdownBasedReference());
933
1056
  }
934
1057
 
935
1058
  restoreScroll(); // don't try this at home kids
@@ -964,7 +1087,7 @@ export default class AmfReference extends LightningElement {
964
1087
  );
965
1088
  }
966
1089
  } else {
967
- this.loadMarkdownBasedReference();
1090
+ this.afterMarkdownTopics(() => this.loadMarkdownBasedReference());
968
1091
  }
969
1092
  }
970
1093
 
@@ -1242,18 +1365,21 @@ export default class AmfReference extends LightningElement {
1242
1365
  }
1243
1366
  });
1244
1367
  } else {
1245
- let invalidTopicReferenceUrl: string | null = "";
1246
- if (topicId) {
1247
- const referenceDetails = this.getRefDetailsForGivenTopicMeta(
1248
- referenceId,
1249
- topicId
1250
- );
1251
- const selectedItemUrl = referenceDetails?.referenceUrl;
1252
- if (!selectedItemUrl) {
1253
- invalidTopicReferenceUrl = previousRefUrlInSession;
1368
+ this.afterMarkdownTopics(() => {
1369
+ let invalidTopicReferenceUrl: string | null = "";
1370
+ if (topicId) {
1371
+ const referenceDetails =
1372
+ this.getRefDetailsForGivenTopicMeta(
1373
+ referenceId,
1374
+ topicId
1375
+ );
1376
+ const selectedItemUrl = referenceDetails?.referenceUrl;
1377
+ if (!selectedItemUrl) {
1378
+ invalidTopicReferenceUrl = previousRefUrlInSession;
1379
+ }
1254
1380
  }
1255
- }
1256
- this.loadMarkdownBasedReference(invalidTopicReferenceUrl);
1381
+ this.loadMarkdownBasedReference(invalidTopicReferenceUrl);
1382
+ });
1257
1383
  }
1258
1384
  }
1259
1385
 
@@ -1491,7 +1617,9 @@ export default class AmfReference extends LightningElement {
1491
1617
  }
1492
1618
  }
1493
1619
  } else {
1494
- this.loadMarkdownBasedReference(name);
1620
+ this.afterMarkdownTopics(() =>
1621
+ this.loadMarkdownBasedReference(name)
1622
+ );
1495
1623
  }
1496
1624
  }
1497
1625
  }
@@ -149,6 +149,7 @@ a,
149
149
  border-width: 0;
150
150
  border-style: solid;
151
151
  border-color: #e2e8f0;
152
+ font-size: var(--dx-g-text-md);
152
153
  color: var(--dx-g-blue-vibrant-50);
153
154
  }
154
155
 
@@ -31,6 +31,7 @@
31
31
  dev-center={devCenter}
32
32
  brand={brand}
33
33
  empty-state-message={emptyStateMessage}
34
+ loading={showSidebarLoading}
34
35
  >
35
36
  <slot name="sidebar-header" slot="version-picker"></slot>
36
37
  </dx-sidebar-old>
@@ -5,6 +5,7 @@ import { closest, querySelector } from "kagekiri";
5
5
  import { toJson, normalizeBoolean } from "dxUtils/normalizers";
6
6
  import { highlightTerms } from "dxUtils/highlight";
7
7
  import { SearchSyncer } from "docUtils/searchSyncer";
8
+ import { loadSidebar } from "docUtils/sidebarLoader";
8
9
  import type { OptionWithLink } from "typings/custom";
9
10
  import { buildDocLinkClickHandler } from "dxUtils/analytics";
10
11
  import ContentActionToolbar from "doc/contentActionToolbar";
@@ -140,7 +141,34 @@ export default class ContentLayout extends LightningElement {
140
141
  }
141
142
 
142
143
  set sidebarContent(value: any) {
143
- this._sidebarContent = toJson(value);
144
+ // An empty attribute means the page has no inline tree (see sidebarSrc).
145
+ this._sidebarContent = value === "" ? null : toJson(value);
146
+ }
147
+
148
+ /**
149
+ * URL of the left-nav JSON, loaded when the page has no inline
150
+ * `sidebar-content`.
151
+ */
152
+ @api
153
+ get sidebarSrc(): string | undefined {
154
+ return this._sidebarSrc;
155
+ }
156
+
157
+ set sidebarSrc(value: string | undefined) {
158
+ this._sidebarSrc = value || undefined;
159
+ if (this.hasConnected) {
160
+ this.loadSidebarContent();
161
+ }
162
+ }
163
+
164
+ /** Set by wrapping layouts that load the sidebar content themselves. */
165
+ @api
166
+ get sidebarLoading(): boolean {
167
+ return this._sidebarLoading;
168
+ }
169
+
170
+ set sidebarLoading(value) {
171
+ this._sidebarLoading = normalizeBoolean(value);
144
172
  }
145
173
 
146
174
  @api
@@ -181,6 +209,14 @@ export default class ContentLayout extends LightningElement {
181
209
 
182
210
  @track
183
211
  protected _sidebarContent: unknown;
212
+ protected _sidebarSrc?: string;
213
+ protected _sidebarLoading = false;
214
+ protected isSidebarSrcLoading = false;
215
+ private hasConnected = false;
216
+
217
+ protected get showSidebarLoading(): boolean {
218
+ return this.sidebarLoading || this.isSidebarSrcLoading;
219
+ }
184
220
 
185
221
  protected _breadcrumbs = null;
186
222
 
@@ -283,6 +319,35 @@ export default class ContentLayout extends LightningElement {
283
319
 
284
320
  // Add click handler for all links
285
321
  this.template.addEventListener("click", this.handleLinkClick);
322
+
323
+ this.hasConnected = true;
324
+ this.loadSidebarContent();
325
+ }
326
+
327
+ /**
328
+ * Loads the sidebar content from `sidebarSrc`. Inline `sidebar-content`
329
+ * wins; on failure the sidebar shows its empty state.
330
+ */
331
+ protected loadSidebarContent(): void {
332
+ const src = this._sidebarSrc;
333
+ if (!src || this._sidebarContent) {
334
+ return;
335
+ }
336
+ this.isSidebarSrcLoading = true;
337
+ loadSidebar(src)
338
+ .then(
339
+ (topics) => {
340
+ if (src === this._sidebarSrc && !this._sidebarContent) {
341
+ this._sidebarContent = topics;
342
+ }
343
+ },
344
+ (error) => console.error(error)
345
+ )
346
+ .then(() => {
347
+ if (src === this._sidebarSrc) {
348
+ this.isSidebarSrcLoading = false;
349
+ }
350
+ });
286
351
  }
287
352
 
288
353
  // Placeholder for childs renderedCallback
@@ -354,6 +419,7 @@ export default class ContentLayout extends LightningElement {
354
419
  }
355
420
 
356
421
  disconnectedCallback(): void {
422
+ this.hasConnected = false;
357
423
  this.disconnectObserver();
358
424
  window.removeEventListener(
359
425
  "highlightedtermchange",
@@ -1,15 +1,7 @@
1
1
  @import "dxHelpers/text";
2
2
 
3
- h1,
4
- h2,
5
- h3,
6
- h4 {
7
- font-weight: var(--dx-g-font-weight-heading, var(--dx-g-font-demi));
8
- }
9
-
10
3
  h1 {
11
- margin: var(--dx-g-space-above-h1, var(--dx-g-spacing-2xl)) 0
12
- var(--dx-g-space-below-h1, var(--dx-g-spacing-md)) 0;
4
+ margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
13
5
  }
14
6
 
15
7
  h1 doc-heading-content {
@@ -17,8 +9,7 @@ h1 doc-heading-content {
17
9
  }
18
10
 
19
11
  h2 {
20
- margin: var(--dx-g-space-above-h2, var(--dx-g-spacing-2xl)) 0
21
- var(--dx-g-space-below-h2, var(--dx-g-spacing-md)) 0;
12
+ margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
22
13
  }
23
14
 
24
15
  h2 doc-heading-content {
@@ -26,8 +17,7 @@ h2 doc-heading-content {
26
17
  }
27
18
 
28
19
  h3 {
29
- margin: var(--dx-g-space-above-h3, var(--dx-g-spacing-xl)) 0
30
- var(--dx-g-space-below-h3, var(--dx-g-spacing-md)) 0;
20
+ margin: var(--dx-g-spacing-xl) 0 var(--dx-g-spacing-md) 0;
31
21
  }
32
22
 
33
23
  h3 doc-heading-content {
@@ -35,8 +25,7 @@ h3 doc-heading-content {
35
25
  }
36
26
 
37
27
  h4 {
38
- margin: var(--dx-g-space-above-h4, var(--dx-g-spacing-lg)) 0
39
- var(--dx-g-space-below-h4, var(--dx-g-spacing-sm)) 0;
28
+ margin: var(--dx-g-spacing-lg) 0 var(--dx-g-spacing-sm) 0;
40
29
  }
41
30
 
42
31
  h4 doc-heading-content {
@@ -13,6 +13,7 @@
13
13
  bail-label={bailLabel}
14
14
  dev-center={devCenter}
15
15
  brand={brand}
16
+ loading={showSidebarLoading}
16
17
  >
17
18
  <slot name="sidebar-header" slot="version-picker"></slot>
18
19
  </dx-sidebar-old>
@@ -7,6 +7,7 @@
7
7
  sidebar-header={sidebarHeader}
8
8
  sidebar-value={sidebarValue}
9
9
  sidebar-content={sidebarContent}
10
+ sidebar-loading={isSidebarLoading}
10
11
  toc-title={tocTitle}
11
12
  toc-options={tocOptions}
12
13
  toc-aria-level={tocAriaLevel}
@@ -1,5 +1,6 @@
1
1
  import { LightningElement, api } from "lwc";
2
2
  import { toJson } from "dxUtils/normalizers";
3
+ import { loadSidebar } from "docUtils/sidebarLoader";
3
4
  import type { OptionWithLink, TreeNode } from "typings/custom";
4
5
 
5
6
  /**
@@ -117,7 +118,61 @@ export default class UnifiedContentLayout extends LightningElement {
117
118
  }
118
119
 
119
120
  set sidebarContent(value: string) {
120
- this._sidebarContent = decorateTopics(toJson(value)?.topics);
121
+ this._sidebarContent =
122
+ value === "" ? null : decorateTopics(toJson(value)?.topics);
123
+ }
124
+
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;
133
+ }
134
+
135
+ set sidebarSrc(value: string | undefined) {
136
+ this._sidebarSrc = value || undefined;
137
+ if (this.hasConnected) {
138
+ this.loadSidebarContent();
139
+ }
140
+ }
141
+
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) {
158
+ return;
159
+ }
160
+
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
+ });
121
176
  }
122
177
 
123
178
  private get enableFooter(): boolean {
@@ -44,7 +44,7 @@ doc-breadcrumbs {
44
44
  gap: var(--dx-g-spacing-xs, 8px);
45
45
  margin-bottom: var(--dx-g-spacing-lg, 16px);
46
46
  color: var(--dx-g-gray-30, #3e3e3c);
47
- font-size: var(--dx-g-font-size-body-3, 14px);
47
+ font-size: var(--dx-g-font-size-sm, 14px);
48
48
  }
49
49
 
50
50
  .read svg {
@@ -1,5 +1,4 @@
1
1
  :host {
2
- /* Deprecated: nothing reads it. Removed under plan 3.3. */
3
2
  --dx-status-icon-color: var(--dx-g-gray-10);
4
3
  --doc-status-vertical-padding: var(--dx-g-spacing-md);
5
4
  }
@@ -0,0 +1,50 @@
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
+ }