@salesforcedevs/docs-components 1.3.169 → 1.3.171-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.3.169",
+    "version": "1.3.171-alpha.0",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
@@ -24,5 +24,5 @@
         "@types/lodash.orderby": "^4.6.7",
         "@types/lodash.uniqby": "^4.7.7"
     },
-    "gitHead": "e819e60b958af0fa567045741481fd7a4e8417b3"
+    "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
 }

package/src/modules/doc/amfReference/amfReference.ts

@@ -2,7 +2,7 @@ import { LightningElement, api, track } from "lwc";
 import { noCase } from "no-case";
 import { sentenceCase } from "sentence-case";
 import qs from "query-string";
-import { AmfModelParser } from "./utils";
+import { AmfModelParser } from "docUtils/amf";
 import { normalizeBoolean } from "dxUtils/normalizers";
 import { CoveoAnalyticsClient } from "coveo.analytics";
 import type {
@@ -30,18 +30,26 @@ import { restoreScroll } from "dx/scrollManager";
 import { DocPhaseInfo } from "typings/custom";
 import { oldVersionDocInfo } from "docUtils/utils";
 
+type NavigationItem = {
+    label: string;
+    name: string;
+    isExpanded: boolean;
+    children: ParsedMarkdownTopic[];
+    isChildrenLoading: boolean;
+};
+
 export default class AmfReference extends LightningElement {
-    @api breadcrumbs?: string | null | undefined = null;
+    @api breadcrumbs: string | null = null;
     @api sidebarHeader!: string;
     @api coveoOrganizationId!: string;
     @api coveoPublicAccessToken!: string;
     @api coveoAnalyticsToken!: string;
     @api coveoAdvancedQueryConfig!: string;
     @api coveoSearchHub!: string;
-    @api useOldSidebar?: boolean = false;
+    @api useOldSidebar: boolean = false;
     @api tocTitle?: string;
     @api tocOptions?: string;
-    @track navigation = [];
+    @track navigation = [] as NavigationItem[];
     @track versions: Array<ReferenceVersion> = [];
     @track showVersionBanner = false;
 
@@ -125,8 +133,8 @@ export default class AmfReference extends LightningElement {
     }
 
     @api
-    get docPhaseInfo() {
-        return this.selectedReferenceDocPhase;
+    get docPhaseInfo(): string | null {
+        return this.selectedReferenceDocPhase || null;
     }
 
     set docPhaseInfo(value: string) {
@@ -151,12 +159,12 @@ export default class AmfReference extends LightningElement {
     protected _referenceSetConfig!: ReferenceSetConfig;
     protected _currentReferenceId = "";
 
-    protected parentReferenceUrls = [];
+    protected parentReferenceUrls = [] as string[];
     protected amfMap: Record<string, AmfModelRecord> = {};
-    protected amfFetchPromiseMap = {};
+    protected amfFetchPromiseMap = {} as any;
     protected metadata: { [key: string]: AmfMetadataTopic } = {};
     protected selectedTopic?: AmfMetaTopicType = undefined;
-    protected selectedSidebarValue = undefined;
+    protected selectedSidebarValue: string | undefined = undefined;
 
     protected selectedVersion: ReferenceVersion | null = null;
 
@@ -347,13 +355,13 @@ export default class AmfReference extends LightningElement {
     /**
      * Returns the selected version or the first available version.
      */
-    private getSelectedVersion(): ReferenceVersion {
+    private getSelectedVersion(): ReferenceVersion | null {
         const versions = this._referenceSetConfig?.versions || [];
         const selectedVersion = versions.find(
             (v: ReferenceVersion) => v.selected
         );
         // return a selected version if there is one, else return the first one.
-        return selectedVersion || (versions.length && versions[0]);
+        return selectedVersion || (versions.length && versions[0]) || null;
     }
 
     private updateAmfConfigInView(): void {
@@ -367,9 +375,11 @@ export default class AmfReference extends LightningElement {
         }
     }
 
-    private async fetchAmf(amfConfig): Promise<AmfModel | AmfModel[]> {
+    private async fetchAmf(
+        amfConfig: AmfConfig
+    ): Promise<AmfModel | AmfModel[]> {
         const { amf } = amfConfig;
-        const response = await fetch(amf, {
+        const response = await fetch(amf!, {
             headers: {
                 "Cache-Control": `max-age=86400`
             }
@@ -388,7 +398,7 @@ export default class AmfReference extends LightningElement {
     /**
      * Returns whether given url is parent reference path like ../example-project/references/reference-id
      */
-    private isParentReferencePath(urlPath: string): boolean {
+    private isParentReferencePath(urlPath?: string | null): boolean {
         if (!urlPath) {
             return false;
         }
@@ -419,9 +429,9 @@ export default class AmfReference extends LightningElement {
      * Populates reference Items from amfConfigList and assigns it to navigation for sidebar
      */
     private populateReferenceItems(): void {
-        const navAmfOrder = [];
+        const navAmfOrder = [] as NavigationItem[];
         for (const [index, amfConfig] of this._amfConfigList.entries()) {
-            let navItemChildren = [];
+            let navItemChildren = [] as ParsedMarkdownTopic[];
             let isChildrenLoading = false;
             if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
                 if (amfConfig.isSelected) {
@@ -441,10 +451,10 @@ export default class AmfReference extends LightningElement {
                 // check whether we should expand all the child nodes, this is required for Coveo to crawl.
                 if (isExpandChildrenEnabled) {
                     this.expandChildrenForMarkdownReferences(
-                        amfConfig.topic.children
+                        amfConfig.topic!.children
                     );
                 }
-                navItemChildren = amfConfig.topic.children;
+                navItemChildren = amfConfig.topic!.children;
             }
             // store nav items for each spec in order
             navAmfOrder[index] = {
@@ -465,7 +475,9 @@ export default class AmfReference extends LightningElement {
      * Returns a boolean indicating whether the children should be expanded or not.
      */
     private isExpandChildrenEnabled(referenceId: string): boolean {
-        return this.expandChildren && this._currentReferenceId === referenceId;
+        return (
+            !!this.expandChildren && this._currentReferenceId === referenceId
+        );
     }
 
     /**
@@ -509,12 +521,12 @@ export default class AmfReference extends LightningElement {
         referenceId: string,
         items: ParsedTopicModel[]
     ): NavItem[] {
-        const methodList = [];
+        const methodList = [] as NavItem[];
 
         items.forEach((item) => {
             item.methods?.forEach((method) => {
                 const title =
-                    this.getTitleForLabel(method.label) || method.method;
+                    this.getTitleForLabel(method.label!) || method.method;
                 const meta = this.addToMetadata(
                     parentReferencePath,
                     referenceId,
@@ -562,7 +574,7 @@ export default class AmfReference extends LightningElement {
         const parentReferencePath = amfConfig.href;
         const model = this.amfMap[referenceId].parser.parsedModel;
 
-        const children = [];
+        const children: any[] = [];
         const expandChildren = this.isExpandChildrenEnabled(referenceId);
 
         NAVIGATION_ITEMS.forEach(
@@ -589,8 +601,8 @@ export default class AmfReference extends LightningElement {
                     }
                     case "endpoint":
                         if (
-                            model[childrenPropertyName] &&
-                            model[childrenPropertyName].length
+                            model[childrenPropertyName!] &&
+                            model[childrenPropertyName!].length
                         ) {
                             const amfTopicId = this.getFormattedIdentifier(
                                 referenceId,
@@ -599,7 +611,7 @@ export default class AmfReference extends LightningElement {
                             const childTopics = this.assignEndpointNavItems(
                                 parentReferencePath,
                                 referenceId,
-                                model[childrenPropertyName]
+                                model[childrenPropertyName!]
                             );
                             children.push({
                                 label,
@@ -614,23 +626,25 @@ export default class AmfReference extends LightningElement {
                         break;
                     case "security":
                     case "type":
-                        if (model[childrenPropertyName]?.length) {
+                        if (model[childrenPropertyName!]?.length) {
                             // Sorting the types alphabetically
-                            model[childrenPropertyName].sort((typeA, typeB) => {
-                                const typeALbl = typeA.label.toLowerCase();
-                                const typeBLbl = typeB.label.toLowerCase();
-                                return typeALbl < typeBLbl
-                                    ? -1
-                                    : typeALbl > typeBLbl
-                                    ? 1
-                                    : 0;
-                            });
+                            model[childrenPropertyName!].sort(
+                                (typeA: any, typeB: any) => {
+                                    const typeALbl = typeA.label.toLowerCase();
+                                    const typeBLbl = typeB.label.toLowerCase();
+                                    return typeALbl < typeBLbl
+                                        ? -1
+                                        : typeALbl > typeBLbl
+                                        ? 1
+                                        : 0;
+                                }
+                            );
                         }
                     // eslint-disable-next-line no-fallthrough
                     default:
                         if (
-                            model[childrenPropertyName] &&
-                            model[childrenPropertyName].length
+                            model[childrenPropertyName!] &&
+                            model[childrenPropertyName!].length
                         ) {
                             const amfTopicId = this.getFormattedIdentifier(
                                 referenceId,
@@ -643,8 +657,8 @@ export default class AmfReference extends LightningElement {
                                     this.metadata[amfTopicId]?.meta
                                 ),
                                 isExpanded: expandChildren,
-                                children: model[childrenPropertyName].map(
-                                    (topic) => {
+                                children: model[childrenPropertyName!].map(
+                                    (topic: any) => {
                                         const meta = this.addToMetadata(
                                             parentReferencePath,
                                             referenceId,
@@ -681,12 +695,18 @@ export default class AmfReference extends LightningElement {
         type: string,
         topic: { id: string; domId: string },
         navTitle: string
-    ): string | undefined {
-        const { urlIdentifer, prefix } = URL_CONFIG[type];
+    ): string {
+        const config = URL_CONFIG[type as keyof typeof URL_CONFIG];
+        const urlIdentifer = config.urlIdentifer;
+        let prefix = null;
+        if ("prefix" in config) {
+            prefix = config.prefix;
+        }
 
         // encodeURI to avoid special characters in the URL meta.
         const identifier =
-            topic[urlIdentifer] && this.encodeIdentifier(topic[urlIdentifer]);
+            urlIdentifer in topic &&
+            this.encodeIdentifier(topic[urlIdentifer as keyof typeof topic]);
         let meta;
         // Assuming that there will be an identifier always
         if (identifier) {
@@ -702,7 +722,7 @@ export default class AmfReference extends LightningElement {
                 navTitle
             };
         }
-        return meta;
+        return meta!;
     }
 
     /**
@@ -713,7 +733,7 @@ export default class AmfReference extends LightningElement {
             (metadata: AmfMetadataTopic) => {
                 return routeMeta.meta === metadata.meta;
             }
-        );
+        )!;
     }
 
     /**
@@ -727,7 +747,7 @@ export default class AmfReference extends LightningElement {
         return Object.values(this.metadata).find(
             (metadata: AmfMetadataTopic) =>
                 referenceId === metadata.referenceId && amfId === metadata.amfId
-        );
+        )!;
     }
 
     /**
@@ -742,7 +762,7 @@ export default class AmfReference extends LightningElement {
             (metadata: AmfMetadataTopic) =>
                 referenceId === metadata.referenceId &&
                 identifier === metadata.identifier
-        );
+        )!;
     }
 
     /**
@@ -756,7 +776,7 @@ export default class AmfReference extends LightningElement {
         return Object.values(this.metadata).find(
             (metadata: AmfMetadataTopic) =>
                 referenceId === metadata.referenceId && type === metadata.type
-        );
+        )!;
     }
 
     /**
@@ -833,9 +853,8 @@ export default class AmfReference extends LightningElement {
             this._currentReferenceId
         );
         if (specBasedReference) {
-            const currentMeta: RouteMeta | null = this.getReferenceMetaInfo(
-                window.location.href
-            );
+            const currentMeta: RouteMeta | undefined =
+                this.getReferenceMetaInfo(window.location.href);
             const metadata =
                 currentMeta && this.getMetadataByUrlQuery(currentMeta);
             if (metadata) {
@@ -871,7 +890,7 @@ export default class AmfReference extends LightningElement {
             this._currentReferenceId
         );
         if (specBasedReference) {
-            const { meta } = this.selectedTopic;
+            const { meta } = this.selectedTopic!;
             const metadata = this.metadata[meta];
             if (metadata) {
                 const {
@@ -988,7 +1007,7 @@ export default class AmfReference extends LightningElement {
      * 1. If the url is encoded already
      * 2. If the url is decoded
      */
-    getUrlEncoded(url: string) {
+    getUrlEncoded(url: string): string {
         // if url matches, then return the encoded url.
         if (decodeURIComponent(url) === url) {
             return encodeURIComponent(url);
@@ -1004,7 +1023,7 @@ export default class AmfReference extends LightningElement {
      * For spec based references gets meta parm from url and then topicId & type from meta
      * For markdown based references gets topicId as last html path in the name, meta & type will be empty
      */
-    getReferenceMetaInfo(referenceUrl: string): RouteMeta | undefined {
+    getReferenceMetaInfo(referenceUrl: string | null): RouteMeta | undefined {
         let metaReferenceInfo;
         if (referenceUrl) {
             const referenceId = this.getReferenceIdFromUrl(referenceUrl);
@@ -1046,10 +1065,10 @@ export default class AmfReference extends LightningElement {
         let topicTitle = "";
         for (let i = 0; i < topics.length; i++) {
             const topic = topics[i];
-            const meta = this.getMarkdownReferenceMeta(topic.link.href);
+            const meta = this.getMarkdownReferenceMeta(topic.link!.href);
             const childTopics = topic.children;
             if (meta === topicMeta) {
-                referenceUrl = topic.link.href;
+                referenceUrl = topic.link!.href;
                 topicTitle = topic.label;
             } else if (childTopics && childTopics.length) {
                 const referenceDetails = this.getReferenceDetailsInGivenTopics(
@@ -1160,7 +1179,7 @@ export default class AmfReference extends LightningElement {
                 }
             });
         } else {
-            let invalidTopicReferenceUrl = "";
+            let invalidTopicReferenceUrl: string | null = "";
             if (topicId) {
                 const referenceDetails = this.getRefDetailsForGivenTopicMeta(
                     referenceId,
@@ -1196,7 +1215,7 @@ export default class AmfReference extends LightningElement {
      * set selected sidebar value as a pathname
      */
 
-    private loadMarkdownBasedReference(referenceUrl?: string): void {
+    private loadMarkdownBasedReference(referenceUrl?: string | null): void {
         let referenceId = "";
         const currentUrl = window.location.href;
         if (this.isProjectRootPath()) {
@@ -1210,7 +1229,7 @@ export default class AmfReference extends LightningElement {
              * CASE2: This case is to navigate to respective reference when the user clicked on root item
              * Ex: .../references/markdown-ref should navigate to first topic.
              */
-            referenceId = this.getReferenceIdFromUrl(referenceUrl);
+            referenceId = this.getReferenceIdFromUrl(referenceUrl!);
         } else if (this.isParentReferencePath(currentUrl)) {
             /**
              * CASE3: This case is to navigate to respective reference when the user entered url with reference id
@@ -1239,9 +1258,9 @@ export default class AmfReference extends LightningElement {
             const amfConfig = this.getAmfConfigWithId(referenceId);
             let redirectReferenceUrl = "";
             if (amfConfig) {
-                const childrenItems = amfConfig.topic.children;
+                const childrenItems = amfConfig.topic!.children;
                 if (childrenItems.length > 0) {
-                    redirectReferenceUrl = childrenItems[0].link.href;
+                    redirectReferenceUrl = childrenItems[0].link!.href;
                 }
             }
             if (redirectReferenceUrl) {
@@ -1375,7 +1394,7 @@ export default class AmfReference extends LightningElement {
 
     handleSelectedItem(): void {
         // update topic view
-        const { referenceId, amfId, type } = this.selectedTopic;
+        const { referenceId, amfId, type } = this.selectedTopic!;
 
         // This updates the component in the content section.
         this.topicModel = {

package/src/modules/doc/amfReference/utils.ts

@@ -1,4 +1,9 @@
-import { AmfHelperMixin } from "@api-components/amf-helper-mixin";
+// @ts-nocheck not going to check this file because it deals almost entirely with the AmfHelperMixin, which is terrible and not worth messing with. We should just upgrade our LWC version instead.
+import {
+    AmfHelperMixin,
+    EndPoint,
+    Operation
+} from "@api-components/amf-helper-mixin";
 import { normalizeDomId } from "dxUtils/normalizers";
 
 const ID_PROPERTY = "@id";
@@ -7,7 +12,7 @@ const TYPE_PROPERTY = "@type";
 export class AmfModelParser extends AmfHelperMixin(Object) {
     _parsedModel = null;
 
-    constructor(api) {
+    constructor(api: any) {
         super();
         if (api) {
             this.amf = Array.isArray(api) ? api[0] : api;
@@ -517,7 +522,7 @@ export class AmfModelParser extends AmfHelperMixin(Object) {
      * @param {string} selected Currently selected `@id`.
      * @return {any|undefined} Model definition for an endpoint fragment.
      */
-    computeEndpointApiModel(model, selectedId) {
+    computeEndpointApiModel(model, selectedId): EndPoint {
         const webApi = this._computeApi(model);
         return this._computeEndpointModel(webApi, selectedId);
     }
@@ -529,7 +534,7 @@ export class AmfModelParser extends AmfHelperMixin(Object) {
      * @param {string} selected Currently selected `@id`.
      * @return {any|undefined} Model definition for an endpoint fragment.
      */
-    computeMethodApiModel(model, selected) {
+    computeMethodApiModel(model, selected): Operation | undefined {
         const webApi = this._computeApi(model);
         return this._computeMethodModel(webApi, selected);
     }
@@ -541,7 +546,7 @@ export class AmfModelParser extends AmfHelperMixin(Object) {
      * @param {string} selected Currently selected `@id`.
      * @return {any|undefined} Model definition for an endpoint fragment.
      */
-    computeEndpointApiMethodModel(model, selected) {
+    computeEndpointApiMethodModel(model, selected): EndPoint | undefined {
         const webApi = this._computeApi(model);
         return this._computeMethodEndpoint(webApi, selected);
     }

package/src/modules/doc/amfTopic/amfTopic.ts

@@ -8,14 +8,15 @@ import {
     createTypeElement
 } from "./utils";
 import type { TopicModel } from "./types";
+import { Json } from "typings/custom";
 
 export default class AmfTopic extends LightningElement {
-    private _model;
-    private amf;
-    private type;
+    private _model: TopicModel | undefined;
+    private amf: Json;
+    private type: string | undefined;
 
     @api
-    get model(): TopicModel {
+    get model(): TopicModel | undefined {
         return this._model;
     }
 
@@ -41,7 +42,11 @@ export default class AmfTopic extends LightningElement {
     }
 
     update(): void {
-        const container = this.template.querySelector("div.topic-container");
+        if (!this.model) {
+            throw new Error("Amf TopicModel undefined when trying to update");
+        }
+
+        const container = this.template.querySelector("div.topic-container")!;
         const { id } = this.model;
         const type = this.type;
         const amf = this.amf;
@@ -79,7 +84,7 @@ export default class AmfTopic extends LightningElement {
         if (container.firstChild) {
             container.firstChild.remove();
         }
-        container.appendChild(element);
+        container.appendChild(element as Node);
     }
 }
 
@@ -89,6 +94,6 @@ export default class AmfTopic extends LightningElement {
  * @param value JSON Serializable object to clone.
  * @returns A copy of Value. One that has been serialized and parsed via JSON. (Functions, Regex, etc are not preserved.)
  */
-function clone(value): object {
+function clone(value: any): any {
     return JSON.parse(JSON.stringify(value));
 }

package/src/modules/doc/amfTopic/types.ts

@@ -1,4 +1,11 @@
 import { Json } from "typings/custom";
+import { AmfModelParser } from "docUtils/amf";
+import {
+    DomainElement,
+    EndPoint,
+    Operation,
+    Shape
+} from "@api-components/amf-helper-mixin";
 
 export type ApiSummaryElement = HTMLElement & {
     amf: Json;
@@ -11,44 +18,39 @@ export type ApiEndpointElement = HTMLElement & {
     inlineMethods: boolean;
     noNavigation: boolean;
     selected: string;
-    endpoint: Json;
+    endpoint: EndPoint;
     noTryIt: boolean;
 };
 
 export type ApiMethodElement = HTMLElement & {
     amf: Json;
     noNavigation: boolean;
-    endpoint: Json;
-    method: Json;
+    endpoint: EndPoint | undefined;
+    method: Operation | undefined;
     noTryIt: boolean;
 };
 
 export type ApiSecurityElement = HTMLElement & {
     amf: Json;
-    security: Json;
+    security: DomainElement | undefined;
 };
 
 export type ApiTypeElement = HTMLElement & {
     amf: Json;
-    type: Json;
+    type?: Shape;
     mediaTypes: Json;
 };
 
 export type ApiDocElement = HTMLElement & {
     amf: Json;
-    shape: Json;
+    shape: DomainElement | undefined;
 };
 
 export type AmfModel = Json;
 
-export interface AmfParser {
-    parse(): void;
-    parsedModel: any;
-}
-
 export interface TopicModel {
     id: string;
     type: string;
     amf: AmfModel;
-    parser: AmfParser;
+    parser: AmfModelParser;
 }

package/src/modules/doc/amfTopic/utils.ts

@@ -1,3 +1,9 @@
+import {
+    DomainElement,
+    EndPoint,
+    Operation,
+    Shape
+} from "@api-components/amf-helper-mixin";
 import type {
     ApiDocElement,
     ApiEndpointElement,
@@ -37,7 +43,7 @@ export function createSummaryElement(amf: Json): HTMLElement {
  */
 export function createEndpointElement(
     amf: Json,
-    endpointModel: Json,
+    endpointModel: EndPoint,
     selected: string
 ): HTMLElement {
     const el: ApiEndpointElement = document.createElement(
@@ -57,8 +63,8 @@ export function createEndpointElement(
  */
 export function createMethodElement(
     amf: Json,
-    endpointMethodModel: Json,
-    methodModel: Json
+    endpointMethodModel: EndPoint | undefined,
+    methodModel: Operation | undefined
 ): HTMLElement {
     const el: ApiMethodElement = document.createElement(
         "api-method-documentation"
@@ -79,7 +85,7 @@ export function createMethodElement(
  */
 export function createSecurityElement(
     amf: Json,
-    securityModel: Json
+    securityModel: DomainElement | undefined
 ): HTMLElement {
     const el: ApiSecurityElement = document.createElement(
         "api-security-documentation"
@@ -98,7 +104,7 @@ export function createSecurityElement(
  */
 export function createTypeElement(
     amf: Json,
-    typeModel: Json,
+    typeModel: Shape | undefined,
     mediaTypes: Json
 ): HTMLElement {
     const el: ApiTypeElement = document.createElement(
@@ -119,7 +125,7 @@ export function createTypeElement(
  */
 export function createDocumentationElement(
     amf: Json,
-    docsModel: Json
+    docsModel: DomainElement | undefined
 ): HTMLElement {
     const el: ApiDocElement = document.createElement(
         "api-documentation-document"