@salesforcedevs/docs-components 0.7.0 → 0.7.59-sppage-alpha2

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

@@ -0,0 +1,1494 @@
+import { LightningElement, api, track } from "lwc";
+import { noCase } from "no-case";
+import { sentenceCase } from "sentence-case";
+import qs from "query-string";
+import { AmfModelParser } from "doc/amfModelParser";
+import { normalizeBoolean, toJson } from "dxUtils/normalizers";
+import type { OptionWithLink } from "typings/custom";
+import type {
+    AmfConfig,
+    AmfMetadataTopic,
+    AmfModel,
+    AmfModelRecord,
+    NavItem,
+    ParsedTopicModel,
+    TopicModel,
+    ReferenceVersion,
+    ReferenceSetConfig,
+    AmfMetaTopicType,
+    RouteMeta,
+    ParsedMarkdownTopic
+} from "./types";
+
+import {
+    NAVIGATION_ITEMS,
+    URL_CONFIG,
+    REFERENCE_TYPES,
+    oldReferenceIdNewReferenceIdMap
+} from "./constants";
+import { restoreScroll } from "dx/scrollManager";
+import { DocPhaseInfo } from "typings/custom";
+import { logCoveoPageView, 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 = null;
+    @api sidebarHeader!: string;
+    @api coveoOrganizationId!: string;
+    @api coveoPublicAccessToken!: string;
+    @api coveoAnalyticsToken!: string;
+    @api coveoSearchHub!: string;
+    @api useOldSidebar: boolean = false;
+    @api tocTitle?: string;
+    @api tocOptions?: string;
+    @api languages!: OptionWithLink[];
+    @api language!: string;
+    @api hideFooter = false;
+    @track navigation = [] as NavigationItem[];
+    @track versions: Array<ReferenceVersion> = [];
+    @track showVersionBanner = false;
+    @track _coveoAdvancedQueryConfig!: { [key: string]: any };
+
+    // Update this to update what component gets rendered in the content block
+    @track
+    protected topicModel!: TopicModel;
+
+    get isVersionEnabled(): boolean {
+        return !!this._referenceSetConfig?.versions?.length;
+    }
+
+    /**
+     * Gives if the currently selected reference is spec based or not
+     */
+    get showSpecBasedReference(): boolean {
+        return this.isSpecBasedReference(this._currentReferenceId);
+    }
+
+    @api
+    get referenceSetConfig(): ReferenceSetConfig {
+        return this._referenceSetConfig;
+    }
+
+    set referenceSetConfig(value: ReferenceSetConfig) {
+        // No change, do nothing.
+        if (value === this._referenceSetConfig) {
+            return;
+        }
+
+        try {
+            const refConfig =
+                typeof value === "string" ? JSON.parse(value) : value;
+            if (!(<ReferenceSetConfig>refConfig).versions) {
+                return;
+            }
+            this._referenceSetConfig = refConfig;
+        } catch (e) {
+            this._referenceSetConfig = {
+                refList: [],
+                versions: []
+            };
+        }
+
+        this._amfConfigList = this._referenceSetConfig.refList || [];
+
+        this._amfConfigList.forEach((amfConfig) => {
+            this._amfConfigMap.set(amfConfig.id, amfConfig);
+        });
+
+        if (this._amfConfigList.length > 0) {
+            this._currentReferenceId =
+                this._referenceSetConfig.refId || this._amfConfigList[0].id;
+        }
+
+        if (this.isVersionEnabled) {
+            const selectedVersion = this.getSelectedVersion();
+
+            /**
+             * If current selected is markdown based reference,
+             * We will assign versions once the selected item url is updated
+             */
+            if (this.isSpecBasedReference(this._currentReferenceId)) {
+                this.versions = this.getVersions();
+            }
+            this.selectedVersion = selectedVersion;
+            if (this.isSpecBasedReference(this._currentReferenceId)) {
+                this.isVersionFetched = true;
+                if (this.oldVersionInfo) {
+                    this.showVersionBanner = true;
+                } else {
+                    this.latestVersion = true;
+                }
+            }
+        } else {
+            this.isVersionFetched = true;
+        }
+
+        // This is to check if the url is hash based and redirect if needed
+        const redirectUrl = this.getHashBasedRedirectUrl();
+        if (redirectUrl) {
+            window.location.href = redirectUrl;
+        } else {
+            this.updateAmfConfigInView();
+        }
+    }
+
+    @api
+    get docPhaseInfo(): string | null {
+        return this.selectedReferenceDocPhase || null;
+    }
+
+    set docPhaseInfo(value: string) {
+        if (value) {
+            this.isParentLevelDocPhaseEnabled = true;
+            this.selectedReferenceDocPhase = value;
+        }
+    }
+
+    @api
+    get expandChildren() {
+        return this._expandChildren;
+    }
+
+    set expandChildren(value) {
+        this._expandChildren = normalizeBoolean(value);
+    }
+
+    /*
+     * The get coveoAdvancedQueryConfig() method returns this._coveoAdvancedQueryConfig,
+     * but before returning it, it checks if there are multiple versions (this.versions.length > 1)
+     * and if a version is selected (this.selectedVersion). If both conditions are met,
+     * it updates the version property of this._coveoAdvancedQueryConfig with the selected version.
+     */
+    @api
+    get coveoAdvancedQueryConfig(): { [key: string]: any } {
+        const coveoConfig = this._coveoAdvancedQueryConfig;
+        if (this.versions.length > 1 && this.selectedVersion) {
+            const currentGAVersionRef = this.versions[0];
+            if (this.selectedVersion.id !== currentGAVersionRef.id) {
+                // Currently Coveo only supports query without "v"
+                const version = this.selectedVersion.id.replace("v", "");
+                coveoConfig.version = version;
+                this._coveoAdvancedQueryConfig = coveoConfig;
+            }
+        }
+        return this._coveoAdvancedQueryConfig;
+    }
+
+    set coveoAdvancedQueryConfig(config) {
+        this._coveoAdvancedQueryConfig = toJson(config);
+    }
+
+    private get enableFooter(): boolean {
+        return !this.hideFooter;
+    }
+
+    // model
+    protected _amfConfigList: AmfConfig[] = [];
+    protected _amfConfigMap: Map<string, AmfConfig> = new Map();
+    protected _referenceSetConfig!: ReferenceSetConfig;
+    protected _currentReferenceId = "";
+
+    protected parentReferenceUrls = [] as string[];
+    protected amfMap: Record<string, AmfModelRecord> = {};
+    protected amfFetchPromiseMap = {} as any;
+    protected metadata: { [key: string]: AmfMetadataTopic } = {};
+    protected selectedTopic?: AmfMetaTopicType = undefined;
+    protected selectedSidebarValue: string | undefined = undefined;
+
+    protected selectedVersion: ReferenceVersion | null = null;
+
+    private hasRendered = false;
+
+    private isParentLevelDocPhaseEnabled = false;
+    private selectedReferenceDocPhase?: string | null = null;
+    private _expandChildren?: boolean = false;
+    private isVersionFetched = false;
+    private latestVersion = false;
+
+    /**
+     * Key for storing the currently selected reference url. This will be used to save the
+     * previously selected reference url and restoring it when changing between reference versions.
+     */
+    private readonly docsReferenceUrlSessionKey: string = "docsReferenceUrl";
+
+    _boundOnApiNavigationChanged;
+    _boundUpdateSelectedItemFromUrlQuery;
+
+    constructor() {
+        super();
+
+        this._boundOnApiNavigationChanged =
+            this.onApiNavigationChanged.bind(this);
+        this._boundUpdateSelectedItemFromUrlQuery =
+            this.updateSelectedItemFromUrlQuery.bind(this);
+    }
+
+    connectedCallback(): void {
+        this.addEventListener(
+            "api-navigation-selection-changed",
+            this._boundOnApiNavigationChanged
+        );
+        window.addEventListener(
+            "popstate",
+            this._boundUpdateSelectedItemFromUrlQuery
+        );
+    }
+
+    disconnectedCallback(): void {
+        this.removeEventListener(
+            "api-navigation-selection-changed",
+            this._boundOnApiNavigationChanged
+        );
+        window.removeEventListener(
+            "popstate",
+            this._boundUpdateSelectedItemFromUrlQuery
+        );
+    }
+
+    renderedCallback(): void {
+        if (!this.hasRendered) {
+            this.hasRendered = true;
+            if (this._amfConfigList && this._amfConfigList.length) {
+                // If amfConfig has a value and length, it is assumed that fetch
+                // has already been called and promises stored.
+                this.updateView();
+            }
+        }
+    }
+
+    /**
+     * Check if the URL hash to see whether this is one we want to redirect
+     * See GUS W-10718771 for references where we want hash-based redirects
+     * Return if we needs to redirect url to updated url
+     */
+    private getHashBasedRedirectUrl(): string | undefined {
+        const { hash } = window.location;
+        let hashBasedRedirectUrl = "";
+        if (hash) {
+            const strippedHash = hash.startsWith("#") ? hash.slice(1) : hash;
+            const strippedHashItems = strippedHash
+                ? strippedHash.split(":")
+                : [];
+            if (strippedHashItems.length) {
+                const referenceId = strippedHashItems[0];
+                const meta = strippedHashItems[1];
+                const encodedMeta = this.getUrlEncoded(meta);
+                const updatedReferenceId =
+                    oldReferenceIdNewReferenceIdMap[referenceId];
+                const newReferenceId = updatedReferenceId || referenceId;
+                const referenceItemConfig =
+                    this.getAmfConfigWithId(newReferenceId);
+                if (referenceItemConfig) {
+                    hashBasedRedirectUrl = `${referenceItemConfig.href}?meta=${encodedMeta}`;
+                }
+            }
+        }
+        return hashBasedRedirectUrl;
+    }
+
+    /**
+     * @param referenceId
+     * @returns AMFConfig with given reference Id
+     */
+    private getAmfConfigWithId(referenceId: string): AmfConfig | undefined {
+        return this._amfConfigMap.get(referenceId);
+    }
+
+    /**
+     * @param referenceId
+     * @returns if the reference is spec based one or not with given referenceId.
+     */
+    private isSpecBasedReference(referenceId: string): boolean {
+        const selectedReference = this.getAmfConfigWithId(referenceId);
+        return selectedReference
+            ? selectedReference.referenceType !== REFERENCE_TYPES.markdown
+            : false;
+    }
+
+    /*
+     * Refactor below method when sidebar allows sending extraData along with the name for each item.
+     * See if we can refactor the below method using regex.
+     */
+
+    /**
+     * @param url
+     * @returns reference Id from url path / selected sidebar item.
+     */
+    private getReferenceIdFromUrl(url: string): string {
+        let referenceId = "";
+        const urlItems = url.split("/references/");
+        if (urlItems.length > 1) {
+            const rightSidePart = urlItems[1];
+
+            //This covers urls like "/project-name/references/reference-id/..."
+            const slashSeparatorItems = rightSidePart.split("/");
+
+            //This covers urls like "/project-name/references/reference-id?meta=Summary"
+            const querySeparatorItems = slashSeparatorItems[0].split("?");
+
+            referenceId = querySeparatorItems[0];
+        }
+
+        return referenceId;
+    }
+
+    private get oldVersionInfo(): DocPhaseInfo | null {
+        let info = null;
+        if (this.versions.length > 1 && this.selectedVersion) {
+            const currentGAVersionRef = this.versions[0];
+            if (this.selectedVersion.id !== currentGAVersionRef.id) {
+                info = oldVersionDocInfo(currentGAVersionRef.link.href);
+            }
+        }
+        return info;
+    }
+
+    /**
+     * @returns versions to be shown in the dropdown
+     * For markdown based specs, Adds selected markdown topic url to same references
+     */
+    private getVersions(): Array<ReferenceVersion> {
+        const allVersions = this._referenceSetConfig.versions;
+        if (!this.isSpecBasedReference(this._currentReferenceId)) {
+            const currentRefMeta = this.getMarkdownReferenceMeta(
+                window.location.href
+            );
+            if (currentRefMeta) {
+                for (let i = 0; i < allVersions.length; i++) {
+                    const versionItem = allVersions[i];
+                    const referenceLink = versionItem.link.href;
+                    const referenceId =
+                        this.getReferenceIdFromUrl(referenceLink);
+                    if (this._currentReferenceId === referenceId) {
+                        // This is to navigate to respective topic in the changed version
+                        versionItem.link.href = `${referenceLink}/${currentRefMeta}`;
+                        allVersions[i] = versionItem;
+                    }
+                }
+            }
+        }
+        return allVersions;
+    }
+
+    /**
+     * Returns the selected version or the first available version.
+     */
+    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]) || null;
+    }
+
+    private updateAmfConfigInView(): void {
+        if (this._amfConfigList && this._amfConfigList.length) {
+            // fetch AMF Json as soon as config is set
+            this.populateReferenceItems();
+            // update() must be called after renderedCallback.
+            if (this.hasRendered) {
+                this.updateView();
+            }
+        }
+    }
+
+    private async fetchAmf(
+        amfConfig: AmfConfig
+    ): Promise<AmfModel | AmfModel[]> {
+        const { amf } = amfConfig;
+        const response = await fetch(amf!, {
+            headers: {
+                "Cache-Control": `max-age=86400`
+            }
+        });
+        const json = await response.json();
+        return json;
+    }
+
+    /**
+     * Returns whether current location is project root path like ../example-project/references
+     */
+    private isProjectRootPath(): boolean {
+        return this.getReferenceIdFromUrl(window.location.href) === "";
+    }
+
+    /**
+     * Returns whether given url is parent reference path like ../example-project/references/reference-id
+     */
+    private isParentReferencePath(urlPath?: string | null): boolean {
+        if (!urlPath) {
+            return false;
+        }
+        const parentReferenceIndex = this.parentReferenceUrls.findIndex(
+            (referenceUrl: string) => {
+                return urlPath.endsWith(referenceUrl);
+            }
+        );
+        return parentReferenceIndex !== -1;
+    }
+
+    /**
+     * Expands the children of Markdown-based References.
+     */
+    private expandChildrenForMarkdownReferences(
+        children: ParsedMarkdownTopic[]
+    ): void {
+        if (!children) {
+            return;
+        }
+        for (const childNode of children) {
+            childNode.isExpanded = true;
+            this.expandChildrenForMarkdownReferences(childNode.children);
+        }
+    }
+
+    /**
+     * Populates reference Items from amfConfigList and assigns it to navigation for sidebar
+     */
+    private populateReferenceItems(): void {
+        const navAmfOrder = [] as NavigationItem[];
+        for (const [index, amfConfig] of this._amfConfigList.entries()) {
+            let navItemChildren = [] as ParsedMarkdownTopic[];
+            let isChildrenLoading = false;
+            if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
+                if (amfConfig.isSelected) {
+                    const amfPromise = this.fetchAmf(amfConfig).then(
+                        (amfJson) => {
+                            this.updateModel(amfConfig.id, amfJson);
+                            this.assignNavigationItemsFromAmf(amfConfig, index);
+                        }
+                    );
+                    this.amfFetchPromiseMap[amfConfig.id] = amfPromise;
+                }
+                isChildrenLoading = true;
+            } else {
+                const isExpandChildrenEnabled = this.isExpandChildrenEnabled(
+                    amfConfig.id
+                );
+                // check whether we should expand all the child nodes, this is required for Coveo to crawl.
+                if (isExpandChildrenEnabled) {
+                    this.expandChildrenForMarkdownReferences(
+                        amfConfig.topic!.children
+                    );
+                }
+                navItemChildren = amfConfig.topic!.children;
+            }
+            // store nav items for each spec in order
+            navAmfOrder[index] = {
+                label: amfConfig.title,
+                name: amfConfig.href,
+                isExpanded:
+                    amfConfig.isSelected ||
+                    this.isExpandChildrenEnabled(amfConfig.id),
+                children: navItemChildren,
+                isChildrenLoading
+            };
+            this.parentReferenceUrls.push(amfConfig.href);
+        }
+        this.navigation = navAmfOrder;
+    }
+
+    /**
+     * Returns a boolean indicating whether the children should be expanded or not.
+     */
+    private isExpandChildrenEnabled(referenceId: string): boolean {
+        return (
+            !!this.expandChildren && this._currentReferenceId === referenceId
+        );
+    }
+
+    /**
+     * Stores fetched AMF JSON value.
+     * Creates and stores a new AmfModelParser instance for the AMF spec.
+     * @param {*} referenceId
+     * @param {*} amf
+     */
+    private updateModel(referenceId: string, amf: AmfModel | AmfModel[]): void {
+        const parser = new AmfModelParser(amf);
+        this.amfMap[referenceId] = {
+            model: amf,
+            parser: parser,
+            parsedModel: parser.parsedModel
+        };
+    }
+
+    /**
+     * Convert any case to a readable Title
+     * ex: snake_case => Snake case
+     * ex: camelCase =>  Camel case
+     * ex: PascalCase => Pascal case
+     * @param label
+     * @returns string
+     */
+    private getTitleForLabel(label: string): string {
+        return sentenceCase(noCase(label));
+    }
+
+    /**
+     * Transforms a list of model data for endpoints into corresponding
+     * navigation list items that are compatible with dx-sidebar.
+     * Compatible with transforming AMF data parsed from both RAML and OAS spec.
+     * Transforms a flat list of endpoints into a nested list based on indentation level
+     * for RAML spec.
+     * @param {Array<Object>} items An array of endpoints.
+     * @returns {array<Object>} List of navigation items
+     */
+    private assignEndpointNavItems(
+        parentReferencePath: string,
+        referenceId: string,
+        items: ParsedTopicModel[]
+    ): NavItem[] {
+        const methodList = [] as NavItem[];
+
+        items.forEach((item) => {
+            item.methods?.forEach((method) => {
+                const title =
+                    this.getTitleForLabel(method.label!) || method.method;
+                const meta = this.addToMetadata(
+                    parentReferencePath,
+                    referenceId,
+                    "method",
+                    method,
+                    title
+                );
+                methodList.push(
+                    Object.assign(method, {
+                        name: this.getReferencePathWithMeta(
+                            parentReferencePath,
+                            meta
+                        ),
+                        label: title
+                    })
+                );
+            });
+        });
+        return methodList;
+    }
+
+    /**
+     * Gives URL path for reference items, Which can be used to push to the history
+     */
+    private getReferencePathWithMeta(
+        parentReferencePath: string,
+        meta: string
+    ): string {
+        // update the encoded url meta param
+        const encodedMeta = meta ? this.getUrlEncoded(meta) : "";
+        return encodedMeta ? `${parentReferencePath}?meta=${encodedMeta}` : "";
+    }
+
+    /**
+     * Assigns Navigation Items to dx-sidebar from the parsed AMF model.
+     * Adds each nav item to the Metadata by type.
+     * The 'summary' nav item has no children.
+     * The 'endpoint' nav item may have nested children.
+     */
+    private assignNavigationItemsFromAmf(
+        amfConfig: AmfConfig,
+        amfIdx: number
+    ): void {
+        const referenceId = amfConfig.id;
+        const parentReferencePath = amfConfig.href;
+        const model = this.amfMap[referenceId].parser.parsedModel;
+
+        const children: any[] = [];
+        const expandChildren = this.isExpandChildrenEnabled(referenceId);
+
+        NAVIGATION_ITEMS.forEach(
+            ({ label, name, childrenPropertyName, type }) => {
+                const indexedName = `${name}-${amfIdx}`;
+                switch (type) {
+                    case "summary": {
+                        const summary = model[type];
+                        const meta = this.addToMetadata(
+                            parentReferencePath,
+                            referenceId,
+                            type,
+                            summary,
+                            label
+                        );
+                        children.push({
+                            label,
+                            name: this.getReferencePathWithMeta(
+                                parentReferencePath,
+                                meta
+                            )
+                        });
+                        break;
+                    }
+                    case "endpoint":
+                        if (
+                            model[childrenPropertyName!] &&
+                            model[childrenPropertyName!].length
+                        ) {
+                            const amfTopicId = this.getFormattedIdentifier(
+                                referenceId,
+                                indexedName
+                            );
+                            const childTopics = this.assignEndpointNavItems(
+                                parentReferencePath,
+                                referenceId,
+                                model[childrenPropertyName!]
+                            );
+                            children.push({
+                                label,
+                                name: this.getReferencePathWithMeta(
+                                    parentReferencePath,
+                                    this.metadata[amfTopicId]?.meta
+                                ),
+                                isExpanded: expandChildren,
+                                children: childTopics
+                            });
+                        }
+                        break;
+                    case "security":
+                    case "type":
+                        if (model[childrenPropertyName!]?.length) {
+                            // Sorting the types alphabetically
+                            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
+                        ) {
+                            const amfTopicId = this.getFormattedIdentifier(
+                                referenceId,
+                                indexedName
+                            );
+                            children.push({
+                                label,
+                                name: this.getReferencePathWithMeta(
+                                    parentReferencePath,
+                                    this.metadata[amfTopicId]?.meta
+                                ),
+                                isExpanded: expandChildren,
+                                children: model[childrenPropertyName!].map(
+                                    (topic: any) => {
+                                        const meta = this.addToMetadata(
+                                            parentReferencePath,
+                                            referenceId,
+                                            type,
+                                            topic,
+                                            topic.label
+                                        );
+                                        return {
+                                            label: topic.label,
+                                            name: this.getReferencePathWithMeta(
+                                                parentReferencePath,
+                                                meta
+                                            )
+                                        };
+                                    }
+                                )
+                            });
+                        }
+                }
+            }
+        );
+
+        this.navigation[amfIdx] = {
+            ...this.navigation[amfIdx],
+            children,
+            isChildrenLoading: false
+        };
+        this.navigation = [...this.navigation];
+    }
+
+    protected addToMetadata(
+        parentReferencePath: string,
+        referenceId: string,
+        type: string,
+        topic: { id: string; domId: string },
+        navTitle: string
+    ): 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 =
+            urlIdentifer in topic &&
+            this.encodeIdentifier(topic[urlIdentifer as keyof typeof topic]);
+        let meta;
+        // Assuming that there will be an identifier always
+        if (identifier) {
+            meta = prefix ? `${prefix}${identifier}` : `${identifier}`;
+            this.metadata[meta] = {
+                parentReferencePath,
+                meta,
+                referenceId,
+                amfId: topic.id,
+                elementId: topic.domId,
+                identifier,
+                type,
+                navTitle
+            };
+        }
+        return meta!;
+    }
+
+    /**
+     * Returns metadata given route meta
+     */
+    protected getMetadataByUrlQuery(routeMeta: RouteMeta): AmfMetadataTopic {
+        return Object.values(this.metadata).find(
+            (metadata: AmfMetadataTopic) => {
+                return routeMeta.meta === metadata.meta;
+            }
+        )!;
+    }
+
+    /**
+     * Returns metadata given reference ID and topic amf ID
+     */
+    protected getMetadataByAmfId(
+        referenceId: string,
+        amfId: string
+    ): AmfMetadataTopic {
+        // Lets make a map based on the hash values so we don't need to loop like this.
+        return Object.values(this.metadata).find(
+            (metadata: AmfMetadataTopic) =>
+                referenceId === metadata.referenceId && amfId === metadata.amfId
+        )!;
+    }
+
+    /**
+     * Returns metadata given reference ID and topic identifier
+     */
+    protected getMetadataByIdentifier(
+        referenceId: string,
+        identifier: string
+    ): AmfMetadataTopic {
+        // Lets make a map based on the hash values so we don't need to loop like this.
+        return Object.values(this.metadata).find(
+            (metadata: AmfMetadataTopic) =>
+                referenceId === metadata.referenceId &&
+                identifier === metadata.identifier
+        )!;
+    }
+
+    /**
+     * Returns metadata given reference ID and topic type
+     */
+    protected getMetadataByType(
+        referenceId: string,
+        type: string
+    ): AmfMetadataTopic {
+        // Lets make a map based on the hash values so we don't need to loop like this.
+        return Object.values(this.metadata).find(
+            (metadata: AmfMetadataTopic) =>
+                referenceId === metadata.referenceId && type === metadata.type
+        )!;
+    }
+
+    /**
+     * Parses URL query params without decoding of params
+     */
+    private parseParams(params: string): qs.ParsedQuery<string> {
+        if (!params) {
+            return {};
+        }
+        return qs.parse(params, {
+            decode: false
+        });
+    }
+
+    /**
+     * Normalizes topic identifier by replacing spaces with '+'
+     * and running encodeURI() on it
+     * @param identifier raw identifier for a topic as parsed from the spec file
+     * @returns normalized and encoded identifier
+     */
+    protected encodeIdentifier(identifier: string): string {
+        let result = identifier.trim();
+        result = result.replace(new RegExp(/\s+/, "g"), "+");
+        return encodeURI(result);
+    }
+
+    /**
+     * Constructs a Reference Topic ID
+     */
+    protected getFormattedIdentifier(referenceId: string, id: string): string {
+        return `${referenceId}:${id}`;
+    }
+
+    protected updateUrlWithSelected(
+        parentReferencePath: string,
+        meta?: string
+    ): void {
+        if (meta) {
+            // update the encoded url meta param
+            const encodedMeta = this.getUrlEncoded(meta);
+
+            window.history.pushState(
+                {},
+                "",
+                `${parentReferencePath}?meta=${encodedMeta}`
+            );
+        }
+    }
+
+    /**
+     * Does a replace on the URL meta, so it does not create a history entry.
+     */
+    protected replaceUrlWithSelected(
+        parentReferencePath: string,
+        meta?: string
+    ): void {
+        if (meta) {
+            // update the encoded url meta param
+            const encodedMeta = this.getUrlEncoded(meta);
+
+            window.history.replaceState(
+                window.history.state,
+                "",
+                `${parentReferencePath}?meta=${encodedMeta}`
+            );
+        }
+    }
+
+    /**
+     * This method gets called when the user navigates back and forth using browser arrows
+     * Updates content depending on the type of reference - spec based or markdown
+     */
+    protected updateSelectedItemFromUrlQuery(): void {
+        const specBasedReference = this.isSpecBasedReference(
+            this._currentReferenceId
+        );
+        if (specBasedReference) {
+            const currentMeta: RouteMeta | undefined =
+                this.getReferenceMetaInfo(window.location.href);
+            const metadata =
+                currentMeta && this.getMetadataByUrlQuery(currentMeta);
+            if (metadata) {
+                const {
+                    parentReferencePath,
+                    referenceId,
+                    amfId,
+                    type,
+                    elementId
+                }: AmfMetadataTopic = metadata;
+                this.loadSpecReferenceContent(
+                    parentReferencePath,
+                    referenceId,
+                    amfId,
+                    type,
+                    elementId,
+                    currentMeta.meta
+                );
+            }
+        } else {
+            this.loadMarkdownBasedReference();
+        }
+
+        restoreScroll(); // don't try this at home kids
+    }
+
+    /**
+     * The API Navigation event will always intend to navigate within the current reference
+     * @param event
+     */
+    protected onApiNavigationChanged(): void {
+        const specBasedReference = this.isSpecBasedReference(
+            this._currentReferenceId
+        );
+        if (specBasedReference) {
+            const { meta } = this.selectedTopic!;
+            const metadata = this.metadata[meta];
+            if (metadata) {
+                const {
+                    parentReferencePath,
+                    referenceId,
+                    amfId,
+                    type,
+                    elementId
+                }: AmfMetadataTopic = metadata;
+                this.loadSpecReferenceContent(
+                    parentReferencePath,
+                    referenceId,
+                    amfId,
+                    type,
+                    elementId,
+                    metadata.meta
+                );
+            }
+        } else {
+            this.loadMarkdownBasedReference();
+        }
+    }
+
+    /**
+     * Updates the currently selected amf and topic
+     */
+    protected loadSpecReferenceContent(
+        parentReferencePath: string,
+        referenceId: string,
+        amfId: string,
+        type: string,
+        elementId: string,
+        meta: string
+    ): void {
+        this.selectedTopic = {
+            referenceId,
+            parentReferencePath,
+            amfId,
+            elementId,
+            type,
+            meta
+        };
+        this.selectedSidebarValue = this.getReferencePathWithMeta(
+            parentReferencePath,
+            meta
+        );
+
+        this.handleSelectedItem();
+
+        this.updateDocPhase();
+    }
+
+    /**
+     * Updates doc phase of selected reference
+     */
+    updateDocPhase(): void {
+        /* If parent level doc phase is enabled, Individual reference level doc phase should not be considered */
+
+        if (!this.isParentLevelDocPhaseEnabled) {
+            const selectedReference = this._amfConfigList.find(
+                (referenceItem: AmfConfig) => {
+                    return referenceItem.id === this._currentReferenceId;
+                }
+            );
+            if (selectedReference) {
+                this.selectedReferenceDocPhase = JSON.stringify(
+                    selectedReference.docPhase
+                );
+            }
+        }
+    }
+
+    /**
+     * Returns the decoded meta query param from given Url as it is being used internally.
+     */
+    getMetaFromUrl(referenceUrl: string): string {
+        const indexOfQueryParam = referenceUrl.indexOf("?");
+        const urlPath = referenceUrl.substring(
+            indexOfQueryParam >= 0 ? indexOfQueryParam : referenceUrl.length
+        );
+        const meta = this.parseParams(urlPath).meta as string;
+        // Always get the meta query param encoded and decode it and store it for internal use
+        // This has 2 advantages,
+        // 1. Supports backward compatible meta query param, so there is no need for redirects.
+        // 2. Supports Prerender and Coveo for their crawling.
+        const encodedMeta = meta && this.getUrlEncoded(meta);
+        const decodedMeta = encodedMeta && decodeURIComponent(encodedMeta);
+        return decodedMeta || "";
+    }
+
+    /**
+     *
+     * @returns meta for given markdown based referenceUrl
+     * Consider last topic url in ../references/reference-name/example.html
+     */
+    getMarkdownReferenceMeta(referenceUrl: string): string {
+        let meta = "";
+        if (referenceUrl) {
+            const slashSeparatorItems = referenceUrl.split("/");
+            const lastItem =
+                slashSeparatorItems[slashSeparatorItems.length - 1];
+            if (lastItem.endsWith(".html")) {
+                meta = lastItem;
+            }
+        }
+        return meta;
+    }
+
+    /**
+     * Gets the encoded url.
+     * This method will return the encoded url for 2 cases,
+     * 1. If the url is encoded already
+     * 2. If the url is decoded
+     */
+    getUrlEncoded(url: string): string {
+        // if url matches, then return the encoded url.
+        if (decodeURIComponent(url) === url) {
+            return encodeURIComponent(url);
+        }
+        // return the encoded url.
+        return this.getUrlEncoded(decodeURIComponent(url));
+    }
+
+    /**
+     *
+     * @returns RouteMeta object for given referenceUrl
+     * referenceId - gets referenceId from url
+     * 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 | null): RouteMeta | undefined {
+        let metaReferenceInfo;
+        if (referenceUrl) {
+            const referenceId = this.getReferenceIdFromUrl(referenceUrl);
+            let meta = "";
+            let topicId = "";
+            let type = "";
+            if (this.isSpecBasedReference(referenceId)) {
+                meta = this.getMetaFromUrl(referenceUrl);
+                if (meta) {
+                    if (meta.includes(":")) {
+                        const metaInfo = meta.split(":");
+                        type = metaInfo[0];
+                        topicId = metaInfo[1] || type;
+                    } else {
+                        topicId = meta;
+                    }
+                }
+            } else {
+                topicId = this.getMarkdownReferenceMeta(referenceUrl);
+            }
+            metaReferenceInfo = {
+                referenceId,
+                meta,
+                topicId,
+                type
+            };
+        }
+        return metaReferenceInfo;
+    }
+
+    /**
+     * Finds and returns referenceUrl and topicTitle if given topic url matches
+     */
+    getReferenceDetailsInGivenTopics(
+        topics: ParsedMarkdownTopic[],
+        topicMeta: string
+    ): { referenceUrl: string; topicTitle: string } {
+        let referenceUrl = "";
+        let topicTitle = "";
+        for (let i = 0; i < topics.length; i++) {
+            const topic = topics[i];
+            const meta = this.getMarkdownReferenceMeta(topic.link!.href);
+            const childTopics = topic.children;
+            if (meta === topicMeta) {
+                referenceUrl = topic.link!.href;
+                topicTitle = topic.label;
+            } else if (childTopics && childTopics.length) {
+                const referenceDetails = this.getReferenceDetailsInGivenTopics(
+                    childTopics,
+                    topicMeta
+                );
+                referenceUrl = referenceDetails.referenceUrl;
+                topicTitle = referenceDetails.topicTitle;
+            }
+            if (referenceUrl && topicTitle) {
+                break;
+            }
+        }
+        return {
+            referenceUrl,
+            topicTitle
+        };
+    }
+
+    /**
+     * Gives referenceUrl and topicTitle for given markdown topic url
+     */
+    getRefDetailsForGivenTopicMeta(
+        referenceId: string,
+        topicMeta: string
+    ): { referenceUrl: string; topicTitle: string } | undefined {
+        const amfConfig = this.getAmfConfigWithId(referenceId);
+        let referenceDetails;
+        if (amfConfig) {
+            const topics = amfConfig.topic?.children || [];
+            referenceDetails = this.getReferenceDetailsInGivenTopics(
+                topics,
+                topicMeta
+            );
+        }
+        return referenceDetails;
+    }
+
+    /**
+     * Updates the DOM on the first load
+     */
+    updateView(): void {
+        const previousRefUrlInSession = window.sessionStorage.getItem(
+            this.docsReferenceUrlSessionKey
+        );
+        window.sessionStorage.removeItem(this.docsReferenceUrlSessionKey);
+        let previousRefInfo = this.getReferenceMetaInfo(
+            previousRefUrlInSession
+        );
+
+        // For spec based reference, We should consider urlData to show same topic when user reloads after navigating to specific topic
+        if (!previousRefInfo) {
+            const currentUrl = window.location.href;
+            const urlReferenceId = this.getReferenceIdFromUrl(currentUrl);
+            if (urlReferenceId && this.isSpecBasedReference(urlReferenceId)) {
+                if (
+                    !this.isProjectRootPath() &&
+                    !this.isParentReferencePath(currentUrl)
+                ) {
+                    previousRefInfo = this.getReferenceMetaInfo(currentUrl);
+                }
+            }
+        }
+
+        let referenceId: string;
+        let topicId = "";
+
+        if (
+            previousRefInfo &&
+            this._amfConfigMap.has(previousRefInfo.referenceId)
+        ) {
+            referenceId = previousRefInfo.referenceId;
+            topicId = previousRefInfo.topicId;
+        } else {
+            referenceId = this._currentReferenceId;
+        }
+
+        const specBasedReference = this.isSpecBasedReference(referenceId);
+        if (specBasedReference) {
+            // Wait till the AMF is loaded.
+            this.amfFetchPromiseMap[referenceId].then(() => {
+                let selectedItemMetaData = this.getMetadataByIdentifier(
+                    referenceId,
+                    topicId
+                );
+                if (!selectedItemMetaData) {
+                    // Doesn't exist, let's use the summary.
+                    selectedItemMetaData = this.getMetadataByType(
+                        referenceId,
+                        "summary"
+                    );
+                }
+
+                if (selectedItemMetaData) {
+                    this.loadSpecReferenceContent(
+                        selectedItemMetaData.parentReferencePath,
+                        selectedItemMetaData.referenceId,
+                        selectedItemMetaData.amfId,
+                        selectedItemMetaData.type,
+                        "",
+                        selectedItemMetaData.meta
+                    );
+
+                    this.updateUrlWithSelected(
+                        selectedItemMetaData.parentReferencePath,
+                        selectedItemMetaData.meta
+                    );
+                    this.updateTags(selectedItemMetaData.navTitle);
+                }
+            });
+        } else {
+            let invalidTopicReferenceUrl: string | null = "";
+            if (topicId) {
+                const referenceDetails = this.getRefDetailsForGivenTopicMeta(
+                    referenceId,
+                    topicId
+                );
+                const selectedItemUrl = referenceDetails?.referenceUrl;
+                if (!selectedItemUrl) {
+                    invalidTopicReferenceUrl = previousRefUrlInSession;
+                }
+            }
+            this.loadMarkdownBasedReference(invalidTopicReferenceUrl);
+        }
+    }
+
+    /**
+     * Navigates to reference of the given URL
+     * @param url
+     */
+    private loadNewReferenceItem(url: string): void {
+        const referenceId = this.getReferenceIdFromUrl(url);
+        const referenceItem = this.getAmfConfigWithId(referenceId);
+        if (referenceItem) {
+            window.location.href = referenceItem.href;
+        }
+    }
+
+    /**
+     * @param referenceUrl to which user wants to navigate
+     * Redirect to first sub item if it's root level item, otherwise content will be loaded
+     * Push the history as a first child item
+     * set selected sidebar value as a pathname
+     */
+
+    private loadMarkdownBasedReference(referenceUrl?: string | null): void {
+        // MILES TODO: figure out if we ever need to log a coveo page view in here
+        // this would be the case if at some point we 'load' a new 'markdown based reference'
+        // without actually triggering a page load
+        let referenceId = "";
+        const currentUrl = window.location.href;
+        if (this.isProjectRootPath()) {
+            /**
+             * CASE1: This case is to consider when the user navigates to references by clicking a project card
+             * Ex: /docs/example-project/references should navigate to the first topic in the first reference
+             */
+            referenceId = this._currentReferenceId;
+        } else if (this.isParentReferencePath(referenceUrl)) {
+            /**
+             * 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!);
+        } else if (this.isParentReferencePath(currentUrl)) {
+            /**
+             * CASE3: This case is to navigate to respective reference when the user entered url with reference id
+             * Ex: .../references/markdown-ref should navigate to first topic.
+             */
+            referenceId = this.getReferenceIdFromUrl(currentUrl);
+        } else if (referenceUrl) {
+            /**
+             * CASE4: This case is to navigate to first item when we don't have topic in the selected version
+             * Ex: .../references/markdown-ref/not-existed-topic-url should navigate to first topic.
+             */
+            const referenceMeta = this.getMarkdownReferenceMeta(referenceUrl);
+            const selectedItemRefId = this.getReferenceIdFromUrl(referenceUrl);
+            const referenceDetails = this.getRefDetailsForGivenTopicMeta(
+                selectedItemRefId,
+                referenceMeta
+            );
+            const selectedItemUrl = referenceDetails?.referenceUrl;
+            if (!selectedItemUrl) {
+                referenceId = this.getReferenceIdFromUrl(referenceUrl);
+            }
+        }
+
+        let isRedirecting = false;
+        if (referenceId) {
+            const amfConfig = this.getAmfConfigWithId(referenceId);
+            let redirectReferenceUrl = "";
+            if (amfConfig) {
+                const childrenItems = amfConfig.topic!.children;
+                if (childrenItems.length > 0) {
+                    redirectReferenceUrl = childrenItems[0].link!.href;
+                }
+            }
+            if (redirectReferenceUrl) {
+                if (this.isParentReferencePath(referenceUrl)) {
+                    // This is for CASE2 mentioned above, Where we need to navigate user to respective href
+                    isRedirecting = true;
+                    window.location.href = redirectReferenceUrl;
+                } else {
+                    // This is for CASE 1,3 and 4 mentioned above, Where we need to update the browser history
+                    window.history.replaceState(
+                        window.history.state,
+                        "",
+                        redirectReferenceUrl
+                    );
+                }
+            }
+        }
+        if (!isRedirecting) {
+            const currentReferenceUrl = window.location.href;
+            const referenceMeta =
+                this.getMarkdownReferenceMeta(currentReferenceUrl);
+            const selectedItemRefId =
+                this.getReferenceIdFromUrl(currentReferenceUrl);
+            const referenceDetails = this.getRefDetailsForGivenTopicMeta(
+                selectedItemRefId,
+                referenceMeta
+            );
+            if (referenceDetails) {
+                this.updateTags(referenceDetails.topicTitle);
+            }
+
+            this.versions = this.getVersions();
+            if (this.oldVersionInfo) {
+                this.showVersionBanner = true;
+            } else {
+                this.latestVersion = true;
+            }
+
+            this.isVersionFetched = true;
+            this.updateDocPhase();
+            this.selectedSidebarValue = window.location.pathname;
+        }
+    }
+
+    /**
+     * Currently, used to handle the version change and store the current reference Url.
+     */
+    handleVersionChange(): void {
+        const currentUrl = window.location.href;
+        window.sessionStorage.setItem(
+            this.docsReferenceUrlSessionKey,
+            currentUrl
+        );
+    }
+
+    handleDismissVersionBanner() {
+        this.showVersionBanner = false;
+    }
+
+    private updateTags(navTitle = ""): void {
+        if (!navTitle) {
+            return;
+        }
+
+        // this is required to update the nav title meta tag.
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        const metaNavTitle = document.querySelector('meta[name="nav-title"]');
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        const titleTag = document.querySelector("title");
+        const TITLE_SEPARATOR = " | ";
+
+        if (metaNavTitle) {
+            metaNavTitle.setAttribute("content", navTitle);
+        }
+
+        /**
+         * Right now, the title tag only changes when you pick a Ref spec,
+         * not every time you choose a subsection of the Ref spec.
+         * This update aims to refresh the title tag with each selection.
+         * If a Ref spec is chosen, we add the value of the <selected topic> to the title.
+         * If a subsection is selected, we update the first part of the current
+         * title with the new <selected topic>.
+         * Example: Following is a sample project structure.
+         * - Project Name
+         *  - Ref Spec1
+         *      - Summary
+         *      - Endpoints
+         *          - E1
+         *          - E2
+         *  - Ref Spec2
+         *      - Summary
+         *      - Endpoints
+         *          - E1 (Selected)
+         *          - E2
+         * Previous Title: Ref Spec2 | Project Name | Salesforce Developer
+         * New Title: E1 | Ref Spec2 | Project Name | Salesforce Developer
+         *
+         */
+        if (titleTag) {
+            let titleTagValue = titleTag.textContent;
+            const titleTagSectionValues: string[] =
+                titleTagValue?.split(TITLE_SEPARATOR);
+            if (titleTagSectionValues) {
+                if (titleTagSectionValues.length <= 3) {
+                    titleTagValue = navTitle + TITLE_SEPARATOR + titleTagValue;
+                } else {
+                    titleTagSectionValues[0] = navTitle;
+                    titleTagValue = titleTagSectionValues.join(TITLE_SEPARATOR);
+                }
+            }
+            titleTag.textContent = titleTagValue;
+        }
+    }
+
+    onNavSelect(event: CustomEvent): void {
+        const name = event.detail.name;
+        if (name) {
+            const urlReferenceId = this.getReferenceIdFromUrl(name);
+            const specBasedReference =
+                this.isSpecBasedReference(urlReferenceId);
+            if (specBasedReference) {
+                const metaVal = this.getMetaFromUrl(name);
+                const currentSelectedMeta = this.selectedTopic
+                    ? this.selectedTopic.meta
+                    : "";
+
+                if (metaVal && metaVal === currentSelectedMeta) {
+                    // selecting the same nav item, skip update
+                    return;
+                }
+
+                const metadata = this.metadata[metaVal];
+                if (metadata) {
+                    const {
+                        parentReferencePath,
+                        referenceId,
+                        amfId,
+                        type,
+                        elementId
+                    } = metadata;
+                    this.loadSpecReferenceContent(
+                        parentReferencePath,
+                        referenceId,
+                        amfId,
+                        type,
+                        elementId,
+                        metaVal
+                    );
+
+                    logCoveoPageView(
+                        this.coveoOrganizationId,
+                        this.coveoAnalyticsToken
+                    );
+                    this.updateUrlWithSelected(parentReferencePath, metaVal);
+                    this.updateTags(metadata.navTitle);
+                } else {
+                    if (this.isParentReferencePath(name)) {
+                        this.loadNewReferenceItem(name);
+                    }
+                }
+            } else {
+                this.loadMarkdownBasedReference(name);
+            }
+        }
+    }
+
+    onExpandCollapse(event: CustomEvent): void {
+        const { name, isSelectAction, isExpanded } = event.detail;
+        if (!isSelectAction && isExpanded) {
+            const referenceId = this.getReferenceIdFromUrl(name);
+            const currentUrl = window.location.href;
+            const currentReferenceId = this.getReferenceIdFromUrl(currentUrl);
+            //No need to do anything if user is expanding currently selected reference
+            if (referenceId !== currentReferenceId) {
+                const isSpecBasedReference =
+                    this.isSpecBasedReference(referenceId);
+                if (isSpecBasedReference) {
+                    // Perform functionality same as item selection
+                    this.onNavSelect(event);
+                }
+            }
+        }
+    }
+
+    handleSelectedItem(): void {
+        // update topic view
+        const { referenceId, amfId, type } = this.selectedTopic!;
+
+        // Adding stringify inside try/catch
+        let amfModelString = "";
+        try {
+            amfModelString = JSON.stringify(this.amfMap[referenceId].model);
+        } catch (error) {
+            console.error(`Error stringifying amf model: ${error}`);
+        }
+
+        // This updates the component in the content section.
+        this.topicModel = {
+            type,
+            amf: amfModelString,
+            parser: this.amfMap[referenceId].parser,
+            id: amfId
+        };
+    }
+}