@salesforcedevs/docs-components 0.56.0 → 0.56.2-comp-flex-ref-2

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

@@ -3,7 +3,6 @@ import { noCase } from "no-case";
 import { sentenceCase } from "sentence-case";
 import qs from "query-string";
 import { AmfModelParser } from "./utils";
-import { RouteMeta } from "./route-meta";
 import type {
     AmfConfig,
     AmfMetadataTopic,
@@ -14,94 +13,46 @@ import type {
     TopicModel,
     ReferenceVersion,
     ReferenceSetConfig,
-    AmfMetaTopicType
+    AmfMetaTopicType,
+    RouteMeta,
+    ParsedMarkdownTopic
 } from "./types";
 
-const NAVIGATION_ITEMS = [
-    {
-        label: "Summary",
-        name: "summary",
-        childrenPropertyName: undefined,
-        type: "summary"
-    },
-    {
-        label: "Endpoints",
-        name: "endpoints",
-        childrenPropertyName: "endpoints",
-        type: "endpoint"
-    },
-    {
-        label: "Documentation",
-        name: "documentation",
-        childrenPropertyName: "docs",
-        type: "documentation"
-    },
-    {
-        label: "Types",
-        name: "types",
-        childrenPropertyName: "types",
-        type: "type"
-    },
-    {
-        label: "Security",
-        name: "security",
-        childrenPropertyName: "security",
-        type: "security"
-    }
-];
-
-const URL_CONFIG = {
-    summary: {
-        urlIdentifer: "label"
-    },
-    endpoint: {
-        urlIdentifer: "path"
-    },
-    method: {
-        urlIdentifer: "label"
-    },
-    documentation: {
-        urlIdentifer: "label"
-    },
-    type: {
-        urlIdentifer: "label",
-        prefix: "type:"
-    },
-    security: {
-        urlIdentifer: "label",
-        prefix: "security:"
-    }
-};
-
-const urlHashToMetaRedirectMap = {
-    "commerce-api-assignments:Summary": "assignments:Summary",
-    "commerce-api-campaigns:Summary": "campaigns:Summary",
-    "commerce-api-catalogs:Summary": "catalogs:Summary",
-    "cdn-zones:Summary": "cdn-api-process-apis:Summary",
-    "inventory-impex:Summary": "impex:Summary",
-    "inventory-reservations:Summary": "inventory-reservation-service:Summary",
-    "shopper-login-and-api-access-service:Summary": "shopper-login:Summary",
-    "shopper-login-and-api-access-service-admin:Summary": "slas-admin:Summary",
-    "einstein-recommendations:Summary": "einstein-api-quick-start-guide:Summary"
-};
+import {
+    NAVIGATION_ITEMS,
+    URL_CONFIG,
+    REFERENCE_TYPES,
+    oldReferenceIdNewReferenceIdMap
+} from "./constants";
 
 export default class AmfReference extends LightningElement {
-    @api breadcrumbs?: string = null;
-    @api sidebarHeader: string;
+    @api breadcrumbs?: string | null | undefined = null;
+    @api sidebarHeader!: string;
     @api coveoOrganizationId!: string;
     @api coveoPublicAccessToken!: string;
     @api coveoAdvancedQueryConfig!: string;
     @api coveoSearchHub!: string;
     @api useOldSidebar?: boolean = false;
+    @api tocTitle?: string;
+    @api tocOptions?: string;
+    @track navigation = [];
+    @track versions: Array<ReferenceVersion> = [];
 
     // Update this to update what component gets rendered in the content block
     @track
-    protected topicModel: TopicModel;
+    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;
@@ -122,22 +73,42 @@ export default class AmfReference extends LightningElement {
             this._referenceSetConfig = refConfig;
         } catch (e) {
             this._referenceSetConfig = {
-                refList: []
+                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();
-            this.versionToRefMap = this._referenceSetConfig.versionToRefMap;
-            // if version is not available, then show empty - this will be the default behaviour
-            this._amfConfig = this.versionToRefMap[selectedVersion.id] || [];
-            this.versions = this._referenceSetConfig.versions;
+
+            /**
+             * 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;
-        } else {
-            this._amfConfig = this._referenceSetConfig.refList;
         }
 
-        this.updateAmfConfigInView();
+        // 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
@@ -153,52 +124,40 @@ export default class AmfReference extends LightningElement {
     }
 
     // model
-    protected _amfConfig: AmfConfig[] = [];
-    protected _referenceSetConfig: ReferenceSetConfig;
+    protected _amfConfigList: AmfConfig[] = [];
+    protected _amfConfigMap: Map<string, AmfConfig> = new Map();
+    protected _referenceSetConfig!: ReferenceSetConfig;
     protected _currentReferenceId = "";
 
+    protected parentReferenceUrls = [];
     protected amfMap: Record<string, AmfModelRecord> = {};
     protected amfFetchPromiseMap = {};
     protected metadata: { [key: string]: AmfMetadataTopic } = {};
-    protected selectedTopic: AmfMetaTopicType = undefined;
-    protected navigation = [];
+    protected selectedTopic?: AmfMetaTopicType = undefined;
     protected selectedSidebarValue = undefined;
-    protected versions: Array<ReferenceVersion> = [];
-    protected selectedVersion: ReferenceVersion = null;
 
-    private hasRendered = false;
-    private navAmfOrder = [];
+    protected selectedVersion: ReferenceVersion | null = null;
 
-    private versionToRefMap: Map<string, Array<AmfConfig>>;
+    private hasRendered = false;
 
     private isParentLevelDocPhaseEnabled = false;
-    private selectedReferenceDocPhase?: string = null;
+    private selectedReferenceDocPhase?: string | null = null;
 
     /**
-     * Key for storing the currently selected reference meta query param. This will be used to save the
-     * previously selected reference meta and restoring it when changing between reference versions.
+     * 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 docsReferenceMetaSessionKey: string = "docsReferenceMeta";
+    private readonly docsReferenceUrlSessionKey: string = "docsReferenceUrl";
 
     _boundOnApiNavigationChanged;
     _boundUpdateSelectedItemFromUrlQuery;
 
-    get amfConfigMapped(): AmfConfig[] {
-        return this._amfConfig.map((config) => {
-            return config.id in this.amfMap
-                ? Object.assign(config, this.amfMap[config.id])
-                : config;
-        });
-    }
-
     constructor() {
         super();
-        this._boundOnApiNavigationChanged = this.onApiNavigationChanged.bind(
-            this
-        );
-        this._boundUpdateSelectedItemFromUrlQuery = this.updateSelectedItemFromUrlQuery.bind(
-            this
-        );
+        this._boundOnApiNavigationChanged =
+            this.onApiNavigationChanged.bind(this);
+        this._boundUpdateSelectedItemFromUrlQuery =
+            this.updateSelectedItemFromUrlQuery.bind(this);
     }
 
     connectedCallback(): void {
@@ -226,7 +185,7 @@ export default class AmfReference extends LightningElement {
     renderedCallback(): void {
         if (!this.hasRendered) {
             this.hasRendered = true;
-            if (this._amfConfig && this._amfConfig.length) {
+            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();
@@ -234,6 +193,108 @@ export default class AmfReference extends LightningElement {
         }
     }
 
+    /**
+     * 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 updatedReferenceId =
+                    oldReferenceIdNewReferenceIdMap[referenceId];
+                const newReferenceId = updatedReferenceId || referenceId;
+                const referenceItemConfig =
+                    this.getAmfConfigWithId(newReferenceId);
+                if (referenceItemConfig) {
+                    hashBasedRedirectUrl = `${referenceItemConfig.href}?meta=${meta}`;
+                }
+            }
+        }
+        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;
+    }
+
+    /**
+     * @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.
      */
@@ -247,9 +308,9 @@ export default class AmfReference extends LightningElement {
     }
 
     private updateAmfConfigInView(): void {
-        if (this._amfConfig && this._amfConfig.length) {
+        if (this._amfConfigList && this._amfConfigList.length) {
             // fetch AMF Json as soon as config is set
-            this.fetchAllAmf();
+            this.populateReferenceItems();
             // update() must be called after renderedCallback.
             if (this.hasRendered) {
                 this.updateView();
@@ -269,17 +330,60 @@ export default class AmfReference extends LightningElement {
     }
 
     /**
-     * Calls the fetch for each AMF in the config.
-     * Stores each fetch promise for handling after renderCallback.
+     * Returns whether current location is project root path like ../example-project/references
      */
-    private fetchAllAmf(): void {
-        for (const [i, amfConfig] of this._amfConfig.entries()) {
-            const p = this.fetchAmf(amfConfig).then((amfJson) => {
-                this.updateModel(amfConfig.id, amfJson);
-                this.assignNavigationItemsFromAmf(amfConfig.id, i);
-            });
-            this.amfFetchPromiseMap[amfConfig.id] = p;
+    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): boolean {
+        if (!urlPath) {
+            return false;
         }
+        const parentReferenceIndex = this.parentReferenceUrls.findIndex(
+            (referenceUrl: string) => {
+                return urlPath.endsWith(referenceUrl);
+            }
+        );
+        return parentReferenceIndex !== -1;
+    }
+
+    /**
+     * Populates reference Items from amfConfigList and assigns it to navigation for sidebar
+     */
+    private populateReferenceItems(): void {
+        const navAmfOrder = [];
+        for (const [index, amfConfig] of this._amfConfigList.entries()) {
+            let navItemChildren = [];
+            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 {
+                navItemChildren = amfConfig.topic.children;
+            }
+            // store nav items for each spec in order
+            navAmfOrder[index] = {
+                label: amfConfig.title,
+                name: amfConfig.href,
+                isExpanded: amfConfig.isSelected,
+                children: navItemChildren,
+                isChildrenLoading
+            };
+            this.parentReferenceUrls.push(amfConfig.href);
+        }
+        this.navigation = navAmfOrder;
     }
 
     /**
@@ -311,7 +415,7 @@ export default class AmfReference extends LightningElement {
 
     /**
      * Transforms a list of model data for endpoints into corresponding
-     * navigation list items that is compatible with dx-sidebar.
+     * 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.
@@ -319,6 +423,7 @@ export default class AmfReference extends LightningElement {
      * @returns {array<Object>} List of navigation items
      */
     private assignEndpointNavItems(
+        parentReferencePath: string,
         referenceId: string,
         items: ParsedTopicModel[]
     ): NavItem[] {
@@ -326,22 +431,35 @@ export default class AmfReference extends LightningElement {
 
         items.forEach((item) => {
             item.methods?.forEach((method) => {
-                const meta = this.addToMetadata(referenceId, "method", method);
+                const meta = this.addToMetadata(
+                    parentReferencePath,
+                    referenceId,
+                    "method",
+                    method
+                );
                 methodList.push(
                     Object.assign(method, {
-                        name: this.getReferencePathWithMeta(meta),
+                        name: this.getReferencePathWithMeta(
+                            parentReferencePath,
+                            meta
+                        ),
                         label:
                             this.getTitleForLabel(method.label) || method.method
                     })
                 );
             });
         });
-
         return methodList;
     }
 
-    private getReferencePathWithMeta(meta: string): string {
-        return meta ? `${window.location.pathname}?meta=${meta}` : "";
+    /**
+     * Gives URL path for reference items, Which can be used to push to the history
+     */
+    private getReferencePathWithMeta(
+        parentReferencePath: string,
+        meta: string
+    ): string {
+        return meta ? `${parentReferencePath}?meta=${meta}` : "";
     }
 
     /**
@@ -351,9 +469,11 @@ export default class AmfReference extends LightningElement {
      * The 'endpoint' nav item may have nested children.
      */
     private assignNavigationItemsFromAmf(
-        referenceId: string,
+        amfConfig: AmfConfig,
         amfIdx: number
     ): void {
+        const referenceId = amfConfig.id;
+        const parentReferencePath = amfConfig.href;
         const model = this.amfMap[referenceId].parser.parsedModel;
 
         const children = [];
@@ -365,13 +485,17 @@ export default class AmfReference extends LightningElement {
                     case "summary": {
                         const summary = model[type];
                         const meta = this.addToMetadata(
+                            parentReferencePath,
                             referenceId,
                             type,
                             summary
                         );
                         children.push({
                             label,
-                            name: this.getReferencePathWithMeta(meta)
+                            name: this.getReferencePathWithMeta(
+                                parentReferencePath,
+                                meta
+                            )
                         });
                         break;
                     }
@@ -385,12 +509,14 @@ export default class AmfReference extends LightningElement {
                                 indexedName
                             );
                             const childTopics = this.assignEndpointNavItems(
+                                parentReferencePath,
                                 referenceId,
                                 model[childrenPropertyName]
                             );
                             children.push({
                                 label,
                                 name: this.getReferencePathWithMeta(
+                                    parentReferencePath,
                                     this.metadata[amfTopicId]?.meta
                                 ),
                                 isExpanded: false,
@@ -425,12 +551,14 @@ export default class AmfReference extends LightningElement {
                             children.push({
                                 label,
                                 name: this.getReferencePathWithMeta(
+                                    parentReferencePath,
                                     this.metadata[amfTopicId]?.meta
                                 ),
                                 isExpanded: false,
                                 children: model[childrenPropertyName].map(
                                     (topic) => {
                                         const meta = this.addToMetadata(
+                                            parentReferencePath,
                                             referenceId,
                                             type,
                                             topic
@@ -438,6 +566,7 @@ export default class AmfReference extends LightningElement {
                                         return {
                                             label: topic.label,
                                             name: this.getReferencePathWithMeta(
+                                                parentReferencePath,
                                                 meta
                                             )
                                         };
@@ -449,46 +578,39 @@ export default class AmfReference extends LightningElement {
             }
         );
 
-        // store nav items for each spec in order
-        this.navAmfOrder[amfIdx] = {
-            label: model.title,
-            name: this.getReferencePathWithMeta(`${referenceId}-root`),
-            isExpanded: amfIdx === 0, // only expand the first spec
-            children
+        this.navigation[amfIdx] = {
+            ...this.navigation[amfIdx],
+            children,
+            isChildrenLoading: false
         };
-
-        // update navigation with each specs nav items as they become available
-        // navigation has to be an array because dx-sidebar expects an array.
-        const navigation = [];
-        for (const navAmf of this.navAmfOrder) {
-            if (navAmf) {
-                navigation.push(navAmf);
-            }
-        }
-        this.navigation = navigation;
+        this.navigation = [...this.navigation];
     }
 
     protected addToMetadata(
+        parentReferencePath: string,
         referenceId: string,
         type: string,
         topic: { id: string; domId: string }
-    ): string {
+    ): string | undefined {
         const { urlIdentifer, prefix } = URL_CONFIG[type];
 
         // encodeURI to avoid special characters in the URL meta.
         const identifier =
             topic[urlIdentifer] && this.encodeIdentifier(topic[urlIdentifer]);
-        const meta = prefix
-            ? `${referenceId}:${prefix}${identifier}`
-            : `${referenceId}:${identifier}`;
-        this.metadata[meta] = {
-            meta: meta,
-            referenceId: referenceId,
-            amfId: topic.id,
-            elementId: topic.domId,
-            identifier,
-            type
-        };
+        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
+            };
+        }
         return meta;
     }
 
@@ -547,54 +669,25 @@ export default class AmfReference extends LightningElement {
     }
 
     /**
-     * Parses url query params without decoding of params
+     * Parses URL query params without decoding of params
      */
-    private parseParams(path: string): qs.ParsedQuery<string> {
-        if (!path) {
+    private parseParams(params: string): qs.ParsedQuery<string> {
+        if (!params) {
             return {};
         }
-        return qs.parse(path, {
+        return qs.parse(params, {
             decode: false
         });
     }
 
-    /**
-     * Gets the portion from the URL query param 'meta'.
-     */
-    protected getCurrentRefMeta(
-        previousRefMetaInSession?: string
-    ): RouteMeta | null {
-        const path = window.location.search;
-        const urlParams = this.parseParams(path);
-        let meta = urlParams.meta as string;
-        let routeMeta = null;
-        if (previousRefMetaInSession) {
-            const refParts = previousRefMetaInSession.split(":");
-            const newRefId = refParts.length > 0 ? refParts[0] : null;
-            const [, type, topicId] = previousRefMetaInSession.split(":");
-            meta = newRefId ? [newRefId, type, topicId].join(":") : null;
-        } else if (!meta) {
-            // If no `meta` explicitly exists, check the URL hash to see whether this is one we
-            // want to redirect (see GUS W-10718771 for one reference where we want hash-based
-            // redirects)
-            const { hash } = window.location;
-            const strippedHash = hash.startsWith("#") ? hash.slice(1) : hash;
-            meta = urlHashToMetaRedirectMap[strippedHash];
-        }
-        if (meta) {
-            routeMeta = new RouteMeta(meta);
-        }
-        return routeMeta;
-    }
-
     /**
      * Normalizes topic identifier by replacing spaces with '+'
      * and running encodeURI() on it
-     * @param identifer raw identifer for a topic as parsed from the spec file
+     * @param identifier raw identifier for a topic as parsed from the spec file
      * @returns normalized and encoded identifier
      */
-    protected encodeIdentifier(identifer: string): string {
-        let result = identifer.trim();
+    protected encodeIdentifier(identifier: string): string {
+        let result = identifier.trim();
         result = result.replace(new RegExp(/\s+/, "g"), "+");
         return encodeURI(result);
     }
@@ -606,86 +699,130 @@ export default class AmfReference extends LightningElement {
         return `${referenceId}:${id}`;
     }
 
-    protected updateSelectedItemFromUrlQuery(): void {
-        const currentMeta: RouteMeta | null = this.getCurrentRefMeta();
-        const metadata = currentMeta && this.getMetadataByUrlQuery(currentMeta);
-        if (metadata) {
-            const {
-                referenceId,
-                amfId,
-                type,
-                elementId
-            }: AmfMetadataTopic = metadata;
-            this.loadContent(
-                referenceId,
-                amfId,
-                type,
-                elementId,
-                currentMeta.meta
-            );
-        }
-    }
-    protected onApiNavigationChanged(): void {
-        // The API Navigation event will always intend to navigate within the current reference
-        const metadata = this.metadata[
-            this.getReferencePathWithMeta(this.selectedTopic.meta)
-        ];
-        const {
-            referenceId,
-            amfId,
-            type,
-            elementId
-        }: AmfMetadataTopic = metadata;
-        this.loadContent(referenceId, amfId, type, elementId, metadata.meta);
-        this.updateUrlWithSelected();
-    }
-
-    protected updateUrlWithSelected(meta?: string): void {
+    protected updateUrlWithSelected(
+        parentReferencePath: string,
+        meta?: string
+    ): void {
         if (meta) {
             window.history.pushState(
                 {},
                 "",
-                `${window.location.pathname}?meta=${meta}`
+                `${parentReferencePath}?meta=${meta}`
             );
         }
     }
 
     /**
-     * Does a replace on the url meta, so it does not create a history entry.
+     * Does a replace on the URL meta, so it does not create a history entry.
      */
-    protected replaceUrlWithSelected(meta?: string): void {
+    protected replaceUrlWithSelected(
+        parentReferencePath: string,
+        meta?: string
+    ): void {
         if (meta) {
             window.history.replaceState(
                 {},
                 "",
-                `${window.location.pathname}?meta=${meta}`
+                `${parentReferencePath}?meta=${meta}`
+            );
+        }
+    }
+
+    /**
+     * 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 | null = 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();
+        }
+    }
+
+    /**
+     * 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 loadContent(
+    protected loadSpecReferenceContent(
+        parentReferencePath: string,
         referenceId: string,
         amfId: string,
         type: string,
-        elementId = "",
-        meta = ""
+        elementId: string,
+        meta: string
     ): void {
         this.selectedTopic = {
             referenceId,
+            parentReferencePath,
             amfId,
             elementId,
             type,
             meta
         };
-        this.selectedSidebarValue = this.getReferencePathWithMeta(meta);
+        this.selectedSidebarValue = this.getReferencePathWithMeta(
+            parentReferencePath,
+            meta
+        );
 
         this.handleSelectedItem();
 
-        // Ensures that the URL always has the meta, that way we don't get two history entries for summary
-        this.replaceUrlWithSelected(meta);
         this.updateDocPhase();
     }
 
@@ -696,10 +833,9 @@ export default class AmfReference extends LightningElement {
         /* If parent level doc phase is enabled, Individual reference level doc phase should not be considered */
 
         if (!this.isParentLevelDocPhaseEnabled) {
-            const referenceId = this.selectedTopic?.referenceId;
-            const selectedReference = this._amfConfig.find(
+            const selectedReference = this._amfConfigList.find(
                 (referenceItem: AmfConfig) => {
-                    return referenceItem.id === referenceId;
+                    return referenceItem.id === this._currentReferenceId;
                 }
             );
             if (selectedReference) {
@@ -711,88 +847,353 @@ export default class AmfReference extends LightningElement {
     }
 
     /**
-     * Updates the DOM on first load
+     * @returns meta query param from given Url
      */
-    updateView(): void {
-        let referenceId: string;
-        let topicId = "";
-        const previousRefMetaInSession = window.sessionStorage.getItem(
-            this.docsReferenceMetaSessionKey
+    getMetaFromUrl(referenceUrl: string): string {
+        const indexOfQueryParam = referenceUrl.indexOf("?");
+        const urlPath = referenceUrl.substring(
+            indexOfQueryParam >= 0 ? indexOfQueryParam : referenceUrl.length
         );
-        window.sessionStorage.removeItem(this.docsReferenceMetaSessionKey);
-        const currentMeta = this.getCurrentRefMeta(previousRefMetaInSession);
-        if (currentMeta) {
-            referenceId = currentMeta.referenceId;
-            topicId = currentMeta.topicId;
-            if (!this.amfFetchPromiseMap[referenceId]) {
-                // This could happen if they specify a bad query value.
-                // In this case, we'll do the logic below to use the default amf
-                referenceId = null;
+        return this.parseParams(urlPath).meta as string;
+    }
+
+    /**
+     *
+     * @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;
+    }
 
-        if (!referenceId) {
-            referenceId = this._amfConfig[0].id;
-            if (!this.amfFetchPromiseMap[referenceId]) {
-                // This should never happen.
-                referenceId = Object.keys(this.amfFetchPromiseMap)[0];
+    /**
+     *
+     * @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): 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;
+    }
 
-        // Wait till the AMF is loaded.
-        this.amfFetchPromiseMap[referenceId].then(() => {
-            let topic = this.getMetadataByIdentifier(referenceId, topicId);
-            if (!topic) {
-                // Doesn't exist, let's use the summary.
-                topic = this.getMetadataByType(referenceId, "summary");
+    /**
+     * Finds and returns referenceUrl if given topic url matches
+     */
+    getReferenceUrlInGivenTopics(
+        topics: ParsedMarkdownTopic[],
+        topicMeta: string
+    ): string {
+        let referenceUrl = "";
+        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;
+            } else if (childTopics && childTopics.length) {
+                referenceUrl = this.getReferenceUrlInGivenTopics(
+                    childTopics,
+                    topicMeta
+                );
             }
+            if (referenceUrl) {
+                break;
+            }
+        }
+        return referenceUrl;
+    }
 
-            if (topic) {
-                this.loadContent(
-                    topic.referenceId,
-                    topic.amfId,
-                    topic.type,
-                    "",
-                    topic.meta
+    /**
+     * Gives referenceUrl for given markdown topic url
+     */
+    getRefLinkForGivenTopicMeta(
+        referenceId: string,
+        topicMeta: string
+    ): string | undefined {
+        const amfConfig = this.getAmfConfigWithId(referenceId);
+        let referenceUrl;
+        if (amfConfig) {
+            const topics = amfConfig.topic?.children || [];
+            referenceUrl = this.getReferenceUrlInGivenTopics(topics, topicMeta);
+        }
+        return referenceUrl;
+    }
+
+    /**
+     * 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
+                    );
+                }
+            });
+        } else {
+            let invalidTopicReferenceUrl = "";
+            if (topicId) {
+                const selectedItemUrl = this.getRefLinkForGivenTopicMeta(
+                    referenceId,
+                    topicId
+                );
+                if (!selectedItemUrl) {
+                    invalidTopicReferenceUrl = previousRefUrlInSession;
+                }
             }
-        });
+            this.loadMarkdownBasedReference(invalidTopicReferenceUrl);
+        }
     }
 
     /**
-     * Currently, used to handle the version change and storing the current meta query param to the session storage.
+     * Navigates to reference of the given URL
+     * @param url
      */
-    handleVersionChange(): void {
-        const path = window.location.search;
-        const urlParams = this.parseParams(path);
-        const meta = urlParams.meta as string;
-        if (meta) {
-            window.sessionStorage.setItem(
-                this.docsReferenceMetaSessionKey,
-                meta
+    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): void {
+        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 selectedItemUrl = this.getRefLinkForGivenTopicMeta(
+                selectedItemRefId,
+                referenceMeta
             );
+            if (!selectedItemUrl) {
+                referenceId = this.getReferenceIdFromUrl(referenceUrl);
+            }
+        }
+
+        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
+                    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({}, "", redirectReferenceUrl);
+                }
+            }
         }
+
+        this.versions = this.getVersions();
+
+        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
+        );
     }
 
     onNavSelect(event: CustomEvent): void {
         const name = event.detail.name;
-        const indexOfQueryParam = name.indexOf("?");
-        const urlPath = name.substring(
-            indexOfQueryParam >= 0 ? indexOfQueryParam : name.length
-        );
-        const metaVal = this.parseParams(urlPath).meta as string;
-        const currentSelectedMeta = this.selectedTopic.meta;
+        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;
+                }
 
-        if (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
+                    );
+                    this.updateUrlWithSelected(parentReferencePath, metaVal);
+                } else {
+                    if (this.isParentReferencePath(name)) {
+                        this.loadNewReferenceItem(name);
+                    }
+                }
+            } else {
+                this.loadMarkdownBasedReference(name);
+            }
         }
+    }
 
-        const metadata = this.metadata[metaVal];
-        if (metadata) {
-            const { referenceId, amfId, type, elementId } = metadata;
-            this.loadContent(referenceId, amfId, type, elementId, metaVal);
-            this.updateUrlWithSelected(metaVal);
+    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);
+                }
+            }
         }
     }