@salesforcedevs/docs-components 0.54.0 → 0.54.5

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

@@ -0,0 +1,813 @@
+import { LightningElement, api, track } from "lwc";
+import { noCase } from "no-case";
+import { sentenceCase } from "sentence-case";
+import qs from "query-string";
+import { AmfModelParser } from "./utils";
+import { RouteMeta } from "./route-meta";
+import type {
+    AmfConfig,
+    AmfMetadataTopic,
+    AmfModel,
+    AmfModelRecord,
+    NavItem,
+    ParsedTopicModel,
+    TopicModel,
+    ReferenceVersion,
+    ReferenceSetConfig,
+    AmfMetaTopicType
+} 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"
+};
+
+export default class AmfReference extends LightningElement {
+    @api breadcrumbs?: string = null;
+    @api sidebarHeader: string;
+    @api coveoOrganizationId!: string;
+    @api coveoPublicAccessToken!: string;
+    @api coveoAdvancedQueryConfig!: string;
+    @api coveoSearchHub!: string;
+    @api useOldSidebar?: boolean = false;
+
+    // Update this to update what component gets rendered in the content block
+    @track
+    protected topicModel: TopicModel;
+
+    get isVersionEnabled(): boolean {
+        return !!this._referenceSetConfig?.versions?.length;
+    }
+
+    @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: []
+            };
+        }
+
+        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;
+            this.selectedVersion = selectedVersion;
+        } else {
+            this._amfConfig = this._referenceSetConfig.refList;
+        }
+
+        this.updateAmfConfigInView();
+    }
+
+    @api
+    get docPhaseInfo() {
+        return this.selectedReferenceDocPhase;
+    }
+
+    set docPhaseInfo(value: string) {
+        if (value) {
+            this.isParentLevelDocPhaseEnabled = true;
+            this.selectedReferenceDocPhase = value;
+        }
+    }
+
+    // model
+    protected _amfConfig: AmfConfig[] = [];
+    protected _referenceSetConfig: ReferenceSetConfig;
+    protected _currentReferenceId = "";
+
+    protected amfMap: Record<string, AmfModelRecord> = {};
+    protected amfFetchPromiseMap = {};
+    protected metadata: { [key: string]: AmfMetadataTopic } = {};
+    protected selectedTopic: AmfMetaTopicType = undefined;
+    protected navigation = [];
+    protected selectedSidebarValue = undefined;
+    protected versions: Array<ReferenceVersion> = [];
+    protected selectedVersion: ReferenceVersion = null;
+
+    private hasRendered = false;
+    private navAmfOrder = [];
+
+    private versionToRefMap: Map<string, Array<AmfConfig>>;
+
+    private isParentLevelDocPhaseEnabled = false;
+    private selectedReferenceDocPhase?: string = 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.
+     */
+    private readonly docsReferenceMetaSessionKey: string = "docsReferenceMeta";
+
+    _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
+        );
+    }
+
+    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._amfConfig && this._amfConfig.length) {
+                // If amfConfig has a value and length, it is assumed that fetch
+                // has already been called and promises stored.
+                this.updateView();
+            }
+        }
+    }
+
+    /**
+     * Returns the selected version or the first available version.
+     */
+    private getSelectedVersion(): ReferenceVersion {
+        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]);
+    }
+
+    private updateAmfConfigInView(): void {
+        if (this._amfConfig && this._amfConfig.length) {
+            // fetch AMF Json as soon as config is set
+            this.fetchAllAmf();
+            // update() must be called after renderedCallback.
+            if (this.hasRendered) {
+                this.updateView();
+            }
+        }
+    }
+
+    private async fetchAmf(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;
+    }
+
+    /**
+     * Calls the fetch for each AMF in the config.
+     * Stores each fetch promise for handling after renderCallback.
+     */
+    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;
+        }
+    }
+
+    /**
+     * 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 is 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(
+        referenceId: string,
+        items: ParsedTopicModel[]
+    ): NavItem[] {
+        const methodList = [];
+
+        items.forEach((item) => {
+            item.methods?.forEach((method) => {
+                const meta = this.addToMetadata(referenceId, "method", method);
+                methodList.push(
+                    Object.assign(method, {
+                        name: this.getReferencePathWithMeta(meta),
+                        label:
+                            this.getTitleForLabel(method.label) || method.method
+                    })
+                );
+            });
+        });
+
+        return methodList;
+    }
+
+    private getReferencePathWithMeta(meta: string): string {
+        return meta ? `${window.location.pathname}?meta=${meta}` : "";
+    }
+
+    /**
+     * 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(
+        referenceId: string,
+        amfIdx: number
+    ): void {
+        const model = this.amfMap[referenceId].parser.parsedModel;
+
+        const children = [];
+
+        NAVIGATION_ITEMS.forEach(
+            ({ label, name, childrenPropertyName, type }) => {
+                const indexedName = `${name}-${amfIdx}`;
+                switch (type) {
+                    case "summary": {
+                        const summary = model[type];
+                        const meta = this.addToMetadata(
+                            referenceId,
+                            type,
+                            summary
+                        );
+                        children.push({
+                            label,
+                            name: this.getReferencePathWithMeta(meta)
+                        });
+                        break;
+                    }
+                    case "endpoint":
+                        if (
+                            model[childrenPropertyName] &&
+                            model[childrenPropertyName].length
+                        ) {
+                            const amfTopicId = this.getFormattedIdentifier(
+                                referenceId,
+                                indexedName
+                            );
+                            const childTopics = this.assignEndpointNavItems(
+                                referenceId,
+                                model[childrenPropertyName]
+                            );
+                            children.push({
+                                label,
+                                name: this.getReferencePathWithMeta(
+                                    this.metadata[amfTopicId]?.meta
+                                ),
+                                isExpanded: false,
+                                children: childTopics
+                            });
+                        }
+                        break;
+                    case "security":
+                    case "type":
+                        if (model[childrenPropertyName]?.length) {
+                            // Sorting the types alphabetically
+                            model[childrenPropertyName].sort((typeA, typeB) => {
+                                const typeALbl = typeA.label.toLowerCase();
+                                const typeBLbl = typeB.label.toLowerCase();
+                                return typeALbl < typeBLbl
+                                    ? -1
+                                    : typeALbl > typeBLbl
+                                    ? 1
+                                    : 0;
+                            });
+                        }
+                    // 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(
+                                    this.metadata[amfTopicId]?.meta
+                                ),
+                                isExpanded: false,
+                                children: model[childrenPropertyName].map(
+                                    (topic) => {
+                                        const meta = this.addToMetadata(
+                                            referenceId,
+                                            type,
+                                            topic
+                                        );
+                                        return {
+                                            label: topic.label,
+                                            name: this.getReferencePathWithMeta(
+                                                meta
+                                            )
+                                        };
+                                    }
+                                )
+                            });
+                        }
+                }
+            }
+        );
+
+        // 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
+        };
+
+        // 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;
+    }
+
+    protected addToMetadata(
+        referenceId: string,
+        type: string,
+        topic: { id: string; domId: string }
+    ): string {
+        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
+        };
+        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(path: string): qs.ParsedQuery<string> {
+        if (!path) {
+            return {};
+        }
+        return qs.parse(path, {
+            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
+     * @returns normalized and encoded identifier
+     */
+    protected encodeIdentifier(identifer: string): string {
+        let result = identifer.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 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 {
+        if (meta) {
+            window.history.pushState(
+                {},
+                "",
+                `${window.location.pathname}?meta=${meta}`
+            );
+        }
+    }
+
+    /**
+     * Does a replace on the url meta, so it does not create a history entry.
+     */
+    protected replaceUrlWithSelected(meta?: string): void {
+        if (meta) {
+            window.history.replaceState(
+                {},
+                "",
+                `${window.location.pathname}?meta=${meta}`
+            );
+        }
+    }
+
+    /**
+     * Updates the currently selected amf and topic
+     */
+    protected loadContent(
+        referenceId: string,
+        amfId: string,
+        type: string,
+        elementId = "",
+        meta = ""
+    ): void {
+        this.selectedTopic = {
+            referenceId,
+            amfId,
+            elementId,
+            type,
+            meta
+        };
+        this.selectedSidebarValue = this.getReferencePathWithMeta(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();
+    }
+
+    /**
+     * 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 referenceId = this.selectedTopic?.referenceId;
+            const selectedReference = this._amfConfig.find(
+                (referenceItem: AmfConfig) => {
+                    return referenceItem.id === referenceId;
+                }
+            );
+            if (selectedReference) {
+                this.selectedReferenceDocPhase = JSON.stringify(
+                    selectedReference.docPhase
+                );
+            }
+        }
+    }
+
+    /**
+     * Updates the DOM on first load
+     */
+    updateView(): void {
+        let referenceId: string;
+        let topicId = "";
+        const previousRefMetaInSession = window.sessionStorage.getItem(
+            this.docsReferenceMetaSessionKey
+        );
+        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;
+            }
+        }
+
+        if (!referenceId) {
+            referenceId = this._amfConfig[0].id;
+            if (!this.amfFetchPromiseMap[referenceId]) {
+                // This should never happen.
+                referenceId = Object.keys(this.amfFetchPromiseMap)[0];
+            }
+        }
+
+        // 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");
+            }
+
+            if (topic) {
+                this.loadContent(
+                    topic.referenceId,
+                    topic.amfId,
+                    topic.type,
+                    "",
+                    topic.meta
+                );
+            }
+        });
+    }
+
+    /**
+     * Currently, used to handle the version change and storing the current meta query param to the session storage.
+     */
+    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
+            );
+        }
+    }
+
+    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 (metaVal === currentSelectedMeta) {
+            // selecting the same nav item, skip update
+            return;
+        }
+
+        const metadata = this.metadata[metaVal];
+        if (metadata) {
+            const { referenceId, amfId, type, elementId } = metadata;
+            this.loadContent(referenceId, amfId, type, elementId, metaVal);
+            this.updateUrlWithSelected(metaVal);
+        }
+    }
+
+    handleSelectedItem(): void {
+        // update topic view
+        const { referenceId, amfId, type } = this.selectedTopic;
+
+        // This updates the component in the content section.
+        this.topicModel = {
+            type,
+            amf: this.amfMap[referenceId].model,
+            parser: this.amfMap[referenceId].parser,
+            id: amfId
+        };
+
+        window.scrollTo({ top: 0, behavior: "smooth" });
+    }
+}